OverlayFS provides a great way to merge directories or filesystems such that one of the filesystems (called the “lower” one) never gets written to, but all changes are made to the “upper” one. This is great for systems that rely on having read-only data, but the view needs to be editable, such as Live CD's and Docker containers/images (image is read only). This also allows you to quickly add some storage to an existing filesystem that is running out of space, without having to alter any structures. It could also be a useful component of a backup/snapshot system.

This guides is tested on Ubuntu 18.04 LTS (GNU/Linux 3.16.57-24 aarch64).

Overlayfs simplest case - Directories Only

The command below creates directories for the lower filesystem, lower filesystem and the merged result which goes into “merged”.

cd /tmp
mkdir -p lower upper workdir overlay
 sudo mount -t overlayfs -o lowerdir=/tmp/lower,upperdir=/tmp/upper/upper,workdir=/tmp/upper/workdir none /tmp/overlay
  • When you create files in lower or uppper, they will appear in the overlay folder.
  • Any files you create in the overlay folder are only created in the upper dir.
  • Changes you make to existing files in the overlay folder only appear in the upper dir.
  • If you delete a file in the overlay folder that was in the lower dir, then a “whiteout” is created so that it does not appear in the overlay folder, but still remains in the lower dir. The same applies to folders.
Example
$ dd if=/dev/zero of=lower-fs.img bs=4096 count=102400
$ mkfs -t ext4 lower-fs.img
$ sudo mount lower-fs.img /tmp/lower
$ sudo chown $USER:$USER /tmp/lower
$ echo "hello world" >> /tmp/lower/lower-file.txt
 
# Remount the lower filesystem as read only just for giggles
$ sudo mount -o remount,ro lower-fs.img /tmp/lower
 
$ dd if=/dev/zero of=upper-fs.img bs=4096 count=102400
$ mkfs -t ext4 upper-fs.img
$ sudo mount upper-fs.img /tmp/upper
$ sudo chown $USER:$USER /tmp/upper
$ mkdir /tmp/upper/upper
$ mkdir /tmp/upper/workdir
$ echo "hello world overlayfs" >> /tmp/upper/upper/upper-file.txt

Note: overlayfs: workdir and upperdir must reside under the same mount

 sudo mount -t overlayfs -o lowerdir=/tmp/lower,upperdir=/tmp/upper/upper,workdir=/tmp/upper/workdir none /tmp/overlay
drwxr-xr-x  1 root root  1024 Apr 11 13:34 .
drwxrwxrwt 12 root root  4096 Apr 11 13:34 ..
drwx------  2 root root 12288 Apr 11 13:27 lost+found
-rw-r--r--  1 root root    12 Apr 11 13:27 lower-file.txt
-rw-r--r--  1 root root    22 Apr 11 13:34 upper-file.txt