What is OverlayFS?

OverlayFS is a union mount filesystem on Linux. It is used to overlay an upper directory tree on top of a lower directory tree – these are virtually merged even if they belong to different filesystems. The interesting thing about OverlayFS is that the lower directory tree is read-only, while the upper partition can be modified. This is a useful mechanism for systems like Live CD’s and Docker containers.

Modifying files

Any changes made to the files from the upper directory tree will be carried out as usual. However, any changes made to the lower tree are temporary and stored on the view level. This means that a copy of the modified files will be created in the upper directory and undergo the changes instead of the original file in the lower layer. If we want these changes to be permanent, another task could copy these modified files from the upper directory into the lower one once modifications are complete.

Removing files

Removing a file from the OverlayFS directory will successfully remove a file from the upper directory, but if the file belongs to the lower directory, OverlayFS will simulate that removal by creating a whiteout file. This file will only exist in the OverlayFS directory – no physical changes will be seen in the other two directories. When OverlayFS is dismounted, this information will be lost, so be mindful if you want these changes to travel to the lower directory.

Implementation

OverlayFS was introduced in Linux in 2014 and has been in the kernel since version 3.18. By default, OverlayFS is enabled. After creating the directories, the following command can be used to mount an overlay:

mount -t overlay overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work /merged

Note: workdir needs to be an empty directory on the same filesystem mount as the upper directory.

If we want to work with multiple lower read-only directories, a list of directories separated by : can be listed like this:

mount -t overlay overlay -o lowerdir=/lower1:/lower2:/lower3,upperdir=/upper,workdir=/work /merged

The order of lower directories is such that the rightmost is the lowest and so on.

If we do not need a writable directory tree because a combination of read-only directories will satisfy our needs, we can use the following command instead of upperdir and workdir:

mount -t overlay overlay -o lowerdir=/lower1:/lower2 /merged

If the kernel does not find upperdir, the overlay is automatically mounted as read-only.