Take the 2-minute tour ×
Ask Ubuntu is a question and answer site for Ubuntu users and developers. It's 100% free, no registration required.

This answer and email message indicate that something called "OverlayFS" is available in Ubuntu 11.10 and will forcefully replace aufs in Ubuntu 12.04.

How do I use it? Where is its documentation?

share|improve this question
    
You and me both, brother. I've come across this so far: mount -t overlayfs -o rw,uppderdir=x,lowerdir=y overlayfs /mount/point. Beyond that I'm clueless. I'm tinkering with it in a live system, but I haven't managed to get it to to work yet. I wish I could find out exactly what "upperdir" and "lowerdir" mean. I've found nothing. –  Githlar Mar 2 '12 at 16:17

5 Answers 5

up vote 24 down vote accepted

I finally managed to find it. I found references to it in the kernel source, but for some reason it doesn't appear in the git tree on kernel.org. But! If you pull the Ubuntu kernel source like this: apt-get source linux-image-3.0.0-16-generic you can find it in linux-3.0.0/Documentation/overlayfs.txt. It is also available in the linux-doc package in /usr/share/doc/linux-doc/filesystems/overlayfs.txt.gz.

As the actual help documentation is more of a "how it works" instead of a "how to mount with it," here's a brief rundown (there is one example in the kernel documentation):

mount -t overlayfs -o [mount options] overlayfs [mountpoint for merged system]

Where [mount options] can be:

  • lowerdir=somedir: lowerdir is the directory you're going to lay your new filesystem over, if there are duplicates these get overwritten by (actually, hidden in favor of) upperdir's version
  • upperdir=somedir: upperdir is the directory you want to overlay lowerdir with. If duplicate filenames exist in lowerdir and upperdir, upperdir's version takes precedence.
  • standard mount options. The only one I've seen from code is ro/rw, but you can experiment.

One thing that confused me at first, so I should probably clarify, is that mounting an overlayfs does not actually mount a filesystem. I was trying to mount a squashfs filesystem using an overlayfs mount, but that's not how it works. You must first mount the (in my case squashfs) filesystem to an arbitrary directory, then use overlayfs to merge the mount point (a directory) and another directory onto a tertiary directory (the overlayfs mount point)(edit: this "tertiary" directory can actually be the upperdir= directory). The tertiary directory is where you will see the merged filesystems (or directory trees - it's flexible).

I've been working on an Ubuntu hybrid boot disk where the base Ubuntu system exists as filesystem.squashfs and I have files called ubuntu.overlay kubuntu.overlay xubuntu.overlay and lubuntu.overlay. The .overlay files are base installs of said systems with the contents of filesystem.squashfs pruned (to save space)(edit: using an overlayfs mount while building each distro eliminates the need to prune the contents of filesystem.squashfs with a script as they don't actually exist in the directory I'm working with! Saves a ton of time.). Then I modified the init scripts to overlay the correct distro's .overlay file (from a boot parameter) using overlayfs and the above options and it works like a charm!

These are the lines that I used in my init scripts (once all variables are translated):

mkdir -p /overlay
mount -t squashfs /cdrom/casper/ubuntu.overlay /overlay
mount -t overlayfs -o lowerdir=/filesystem.squashfs,upperdir=/overlay overlayfs /

Note that filesystem.squashfs above is a directory created by casper, not a file.

share|improve this answer
1  
Where did you find this? –  ændrük Mar 3 '12 at 19:43
    
It was in the documentation as described above. It gave one example and I just extrapolated off it. The documentation gives a very deep explanation of how the filesystem itself works. –  Githlar Mar 4 '12 at 15:15
3  
"but for some reason it doesn't appear in the git tree on kernel.org" - That's because overlayfs is not in upstream kernel, just like aufs isn't (and won't ever be). Such union filesystems are integrated by Ubuntu Kernel Team. –  MestreLion May 19 '12 at 13:18
    
That's a handy bit of info, thanks! –  Githlar Sep 19 '12 at 6:25
1  
OverlayFS is apparently getting into kernel 3.10. –  David C. Bishop Mar 17 '13 at 3:57

I have extended these artikels to include a Script for overlayfs that sets up a read-only root fs.

Hope it helps.

share|improve this answer
    
Thanks to the work that others did, Dustin and I have added a banary package named 'overlayroot' to quantal, which is part of the cloud-initramfs-tools source package. See usage documentation in /etc/overlayroot.conf –  smoser Jul 31 '12 at 14:37

Here is an online, current version of Documentation/filesystems/overlayfs.txt (mirror).

share|improve this answer
mount -t  overlayfs overlayfs  /path/to/mountpoint  -o  rw,uppderdir=/path/to/upperdir, lowerdir=/path/to/lowerdir 

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. It would be more correct to refer to an upper and lower 'directory tree' rather than 'filesystem' as it is quite possible for both directory trees to be in the same filesystem and there is no requirement that the root of a filesystem be given for either upper or lower. The lower filesystem can be any filesystem supported by Linux and does not need to be writable. The lower filesystem can even be another overlayfs. The upper filesystem will normally be writable and if it is it must support the creation of trusted.* extended attributes, and must provide valid d_type in readdir responses, so NFS is not suitable. A read-only overlay of two read-only filesystems may use any filesystem type.

Overlaying mainly involves directories. If a given name appears in both upper and lower filesystems and refers to a non-directory in either, then the lower object is hidden - the name refers only to the upper object. Where both upper and lower objects are directories, a merged directory is formed. At mount time, the two directories given as mount options "lowerdir" and "upperdir" are combined into a merged directory: mount -t overlayfs overlayfs -olowerdir=/lower,upperdir=/upper,\ workdir=/work /merged The "workdir" needs to be an empty directory on the same filesystem as upperdir. Then whenever a lookup is requested in such a merged directory, the lookup is performed in each actual directory and the combined result is cached in the dentry belonging to the overlay filesystem. If both actual lookups find directories, both are stored and a merged directory is created, otherwise only one is stored: the upper if it exists, else the lower. Only the lists of names from directories are merged. Other content such as metadata and extended attributes are reported for the upper directory only. These attributes of the lower directory are hidden. whiteouts and opaque directories

share|improve this answer

this is what i found

http://home.comcast.net/~artn/ovlfs/ovl.man.txt

hope that helps

share|improve this answer
    
Welcome to Ask Ubuntu! Whilst this may theoretically answer the question, it would be preferable to include the essential parts of the answer here, and provide the link for reference. –  jrg Mar 2 '12 at 20:06
2  
Also, ovlfs isn't the same as overlayfs... I know, these VFS's can be confusing in their names. –  Githlar Mar 2 '12 at 21:04

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.