OverlayFS – Example OverlayFS Usage

overlayfs

I'm running Ubuntu 14.04 with the 3.19 kernel which should have OpenFS supported (since kernel 3.18). I've been reading about OverlayFS but am confused as to how to actually implement using it. It looks like it could be a really useful alternative to LVM in enabling changes to be written somewhere else whilst taking a backup of the original filesystem that is being overlayed?

Can someone give me the example mount commands to use (if possible) for the following cases:

  • With a raw disk image (created using dd if=/dev/zero of=$HOME/filestystem1.img bs=4096 count=1024000) to act as the overlaying filesystem, mount it over the top of my host's filesystem at $HOME/mount which should already contain some random files such as file1.txt and file2.txt. Once mounted I believe that I should still be able to see my already existing files and any files I now create will actually be stored inside the filesystem1.img file that I could possibly move to another system?

  • Create another raw disk image and mount this one on top of the other one we just created. Do I do this as a second mount command that is executed after mount command we ran in the previous example, or can I possibly specify both mounts in one go?

I can't tell if OverlayFS is an actual filesystem I need to create on the disk images with mkfs -t xxx /path/to/raw/disk/image, or is a special mounting method and the raw disk images are actually using something like ext4, but they are mounted in a special way with mount -t OverlayFS? When I run:

cd /sbin
ls mkfs*

I get the following which do not show an option to make an overlay filesystem.

mkfs      mkfs.cramfs  mkfs.ext3  mkfs.ext4dev  mkfs.minix  mkfs.ntfs
mkfs.bfs  mkfs.ext2    mkfs.ext4  mkfs.fat      mkfs.msdos  mkfs.vfat

Best Answer

I can't tell if OverlayFS is an actual filesystem I need to create on the disk images with mkfs -t xxx /path/to/raw/disk/image, or is a special mounting method and the raw disk images are actually using something like ext4, but they are mounted in a special way with mount -t OverlayFS?

One does not need to run any mkfs command for overlayFS, it is just a way of mounting.

Once mounted I believe that I should still be able to see my already existing files and any files I now create will actually be stored inside the filesystem1.img file that I could possibly move to another system?

Yes, for a more detailed explanation of how OverlayFS works, you may wish to refer to "Docker and OverlayFS in practice".

Examples

Creating an overlay mount can be done purely with directories if desired as demonstrated here:

cd /tmp
mkdir lower upper workdir overlay
sudo mount -t overlay -o \
lowerdir=/tmp/lower,\
upperdir=/tmp/upper,\
workdir=/tmp/workdir \
none /tmp/overlay

You can throw in [virtual] block devices with their own filesystems (of any kind) to act as the lower and upper filesystems if you desire. The only restriction is that the "workdir" needs to be an empty directory within the same filesystem as the upperdir. An example using a filesystem for both the upperdir and lowerdir can be shown below:

cd /tmp

# Create the necessary directories.
mkdir lower upper overlay

# Lets create a fake block device to hold our "lower" filesystem
dd if=/dev/zero of=lower-fs.img bs=4096 count=102400
dd if=/dev/zero of=upper-fs.img bs=4096 count=102400

# Give this block device an ext4 filesystem.
mkfs -t ext4 lower-fs.img
mkfs -t ext4 upper-fs.img

# Mount the filesystem we just created and give it a file
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

# Mount the upper filesystem
sudo mount upper-fs.img /tmp/upper
sudo chown $USER:$USER /tmp/upper

# Create the workdir in the upper filesystem and the 
# directory in the upper filesystem that will act as the upper
# directory (they both have to be in the same filesystem)
mkdir /tmp/upper/upper
mkdir /tmp/upper/workdir

# Create our overlayfs mount
sudo mount -t overlay -o \
lowerdir=/tmp/lower,\
upperdir=/tmp/upper/upper,\
workdir=/tmp/upper/workdir \
none /tmp/overlay

The examples above are taken from my blog post on using overlayfs.

Nesting OverlayFS

... another raw disk image and mount this one on top of the other one we just created. Do I do this as a second mount command that is executed after mount command we ran in the previous example, or can I possibly specify both mounts in one go?

You can nest overlayFS. For example, you can nest the example above as the lowerdir to another overlayFS system by running:

mkdir -p /tmp/upperdir2/upper /tmp/upperdir2/workdir /tmp/overlay2
sudo mount -t overlay -o \
lowerdir=/tmp/overlay,\
upperdir=/tmp/upperdir2/upper,\
workdir=/tmp/upperdir2/workdir \
none /tmp/overlay2

When Ubuntu gets kernel 4.0+, we should be able to combine multiple lower directories in a single command by using the colon character as a separator like so:

sudo mount -t overlay -o \
lowerdir=/tmp/lower:/tmp/lowest,\
upperdir=/tmp/upper,\
workdir=/tmp/workdir \
none /tmp/overlay

In this case, you do not have two workdirs but one, and you keep the same merged path of /tmp/overlay. The lower directories will be stacked from right to left. You can also omit upperdir= entirely, which results in a readonly mount.

Related Question