OverlayFS

This page documents few use cases that makes use of OverlayFS in Alpine Linux installations. An OverlayFS also known as overlay-filesystem, tries to present a filesystem which is the result of overlaying one filesystem on top of the other.

An overlay filesystem combines two filesystems - an ‘upper’ filesystem and a ‘lower’ filesystem. When a name exists in both filesystems, the object in the ‘upper’ filesystem is visible while the object in the ‘lower’ filesystem is either hidden or, in the case of directories, merged with the ‘upper’ object.

Loopback image with overlayfs

When Alpine Linux runs in diskless mode, the entire system is loaded into memory at boot. For memory constrained devices like Raspberry Pi models(3A+,Pi0) with only 512M of RAM, you may want additional storage i.e more space than offered by your RAM. This additional storage need can be met by creating a loop-back storage on the SD card or any writable storage mounted with overlayfs.

First, make the SD card writable again and change fstab to always do so:

mount /media/mmcblk0p1 -o rw,remount sed -i 's/vfat\ ro,/vfat\ rw,/' /etc/fstab

Create the loop-back file, this example is 1 GB:

dd if=/dev/zero of=/media/mmcblk0p1/persist.img bs=1024 count=0 seek=1048576

Install the ext4 utilities:

apk add e2fsprogs

Format the loop-back file:

mkfs.ext4 /media/mmcblk0p1/persist.img

Mount the storage:

echo "/media/mmcblk0p1/persist.img /media/persist ext4 rw,relatime,errors=remount-ro 0 0" >> /etc/fstab mkdir /media/persist mount -a

Note: Overlay workdir needs to be an empty directory on the same filesystem mount as the upper directory. So each overlay must use its own workdir.

Make the overlay folders, we are using the /usr directory here, but you can use /home or anything else.

mkdir /media/persist/usr mkdir /media/persist/.work_usr echo "overlay /usr overlay lowerdir=/usr,upperdir=/media/persist/usr,workdir=/media/persist/.work_usr 0 0" >> /etc/fstab mount -a

Your /etc/fstab file should look something like this:

Contents of /etc/fstab

/dev/cdrom /media/cdrom iso9660 noauto,ro 0 0 /dev/usbdisk /media/usb vfat noauto,ro 0 0 /dev/mmcblk0p1 /media/mmcblk0p1 vfat rw,relatime,fmask=0022,dmask=0022,errors=remount-ro 0 0 /media/mmcblk0p1/persist.img /media/persist ext4 rw,relatime,errors=remount-ro 0 0 overlay /usr overlay lowerdir=/usr,upperdir=/media/persist/usr,workdir=/media/persist/.work_usr 0 0

Now commit the changes: (optionally remove the e2fsprogs, but it does contain repair tools)

lbu_commit -d

Remember, with this setup if you install things and you have done this overlay for /usr, you must not commit the 'apk add', otherwise, while it boots it will try and install it to memory, not to the persistent storage.

If you do want to install something small at boot, you can use apk add and lbu commit -d.

If it is something a bit bigger, then you can use apk add but then not commit it. It will be persistent (in /usr), but be sure to check everything you need is in that directory and not in folders you have not made persistent.

Overlay root filesystem

In certain devices like pi, Sys mode leads to constant writing to the sd card. Overlay root filesystem can be enabled by adding the option overlaytmpfs=yes to the Kernel command-line parameters. This will cause the underlying root filesystem to be mounted read-only, with an overlayed tmpfs for modifications which will be discarded at shutdown. This option will avoid constant writing to the disk.

In pi, adding the parameter to /boot/cmdline.txt file saves constant writing to the sd-card. The /boot/cmdline.txt file appears as follows

Contents of /boot/cmdline.txt

root=UUID=afaa7f11-8191-4fbc-9e45-62113f61e1b4 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4 overlaytmpfs=yes

The below output shows how the filesystem is mounted when OverlayFS for root is enabled:

# df -m

Filesystem           1M-blocks      Used Available Use% Mounted on
...
/dev/mmcblk0p2           59555       326     56172   1% /media/root-ro
root-tmpfs                 225        13       211   6% /media/root-rw
overlayfs                  225        13       211   6% /
...

# mount
...
/dev/mmcblk0p2 on /media/root-ro type ext4 (ro,relatime)
root-tmpfs on /media/root-rw type tmpfs (rw,relatime,mode=755)
overlayfs on / type overlay (rw,relatime,lowerdir=/media/root-ro,upperdir=/media/root-rw/root,workdir=/media/root-rw/work,uuid=on)
...

Removing and adding back the overlaytmpfs=yes option in the /boot/cmdline.txt file using a toggle script will allow easy maintenance on the pi and any software/configuration can be easily added/removed.

See also

• Diskless Mode
• OverlayFS page in Kernel.org
• Gentoo wiki OverlayFS page
• Archwiki OverlayFS page