Simple OverlayFS

Mon 08 December 2014 | -- (permalink)

These are some notes to help myself remember the basic usage and mechanics of overlayfs, as well as explain them to others.

These steps are performed in an Ubuntu 14.04 (Trusty) Vagrant box, which comes with OverlayFS support out of the box.

First make 3 folders:

# mkdir base_folder
# mkdir overlay_folder
# mkdir work_folder

Put some dummy files in the base and overlay folders. We'll watch how their contents change after later steps.

# echo "I am in the base" > base_folder/base_file
# echo "I am in the overlay" > overlay_folder/overlay_file

Now mount the overlayfs

# mount -t overlayfs -o lowerdir=/home/vagrant/base_folder,upperdir=/home/vagrant/overlay_folder overlayfs /home/vagrant/work_folder

Now in the work folder we should see files from both the base and the overlay:

# ls work_folder/
base_file  overlay_file

Now let's try making a new file in the work folder mount point.

# echo "i am in the work folder" > work_folder/work_file

You should see the new file in the work folder, as well as in the overlay folder.

# ls work_folder/
base_file  overlay_file  work_file

# ls overlay_folder/
overlay_file  work_file

You will not see the new file in the base.

# ls base_folder/
base_file

Now let's try modifying a file that is in the base, from the work folder mountpoint.

# echo "this is new content in the base file" > work_folder/base_file 

You'll see your changes in the work folder and the overlay folder, but not in the base.

# cat work_folder/base_file 
this is new content in the base file

# cat overlay_folder/base_file 
this is new content in the base file

# cat base_folder/base_file 
I am in the base

Now try modifying a file from the overlay, while in the work folder.

# echo "this is new content in the overlay file" > work_folder/overlay_file 

You'll see that your changes exist in the work folder and in the overlay, but the file still doesn't exist in the base.

# cat work_folder/overlay_file 
this is new content in the overlay file

# cat overlay_folder/overlay_file 
this is new content in the overlay file

# ls base_folder/
base_file

OverlayFS is used by the Velociraptor project that we've built at YouGov, which provides a Heroku-compatible platform for deploying applications on Linux.

OverlayFS is expected to be part of Linux kernel 3.18, though you can get it now in Ubuntu.