Writable overlays (a.k.a. union mounts)

Writable overlays (a.k.a., union mounts)

Writable overlays are a specialized subset of union mounts that let you mount exactly one read-write file system over exactly one read-only file system. The top layer file system must support whiteouts and fallthrus, special kinds of directory entries. Currently, ext2, jffs2, and tmpfs have fallthru and whiteout support.

The latest most up to date version of writable overlay documentation is here:

Writable overlays (a.k.a. union mounts) design document

FAQ

Q: Can I union two or more read-only file systems together?
A: Not right now, perhaps later if we figure out some locking problems.

Most people want to union several read-only file systems together as an easy way of constructing disk images with certain sets of packages. In general, if you want to use union mounts to solve a packaging or file system image building problem, you should use a system configuration management tool like Puppet:

http://reductivelabs.com/trac/puppet/

Think about this question: What does your package manager's database file contain when you build an image out of several file system layers? A union file system can't merge a package manager database.
Q: Can I use a read-only file system as the top layer?
A: No. This may change.
Q: Do chmod()/chattr()/chown()/link() work?
A: Not right now. They should in a few weeks.
Q: I have more questions. What should I do?
A: Email linux-fsdevel@vger.kernel.org and CC vaurora@redhat.com.

Getting the code

Writable overlays require patches to the kernel, e2fsprogs, and util-linux. All patches are maintained in public git repos, linked to below.

Kernel

http://git.kernel.org/?p=linux/kernel/git/val/linux-2.6.git;a=summary

    $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/val/linux-2.6.git

The name of the most up to date branch changes a lot; send email if you need to know exactly what it is this week. At present, the most up-to-date branch is "overlay". Currently, only tmpfs, ext2, and jffs2 have support to be the read-write layer.

NB: this won't compile for UML with gcc 4.3, use make ARCH=um CC=gcc34/.

e2fsprogs

http://git.kernel.org/?p=fs/ext2/val/e2fsprogs.git;a=summary

    $ git clone git://git.kernel.org/pub/scm/fs/ext2/val/e2fsprogs.git

util-linux

util-linux git repo - see "union_mount" branch

    $ git clone git://git.kernel.org/pub/scm/utils/util-linux-ng/val/util-linux-ng.git

Union mount UML dev kit

Download the following enormous tarball and you'll get a complete union mount on User Mode Linux development environment (along with above git repos, of course). It is x86_64 only. You must have the union mount e2fsprogs and util-linux installed on your development machine in order to rebuild the test disk images for UML.

Union mount UML devkit

A copy of the developer's README from the devkit is here:

Developer README

Please send corrections, suggestions, new patch sources, etc. to:

vaurora at redhat dot com
jblunck at suse dot de
linux-fsdevel at vger dot kernel dot org

Contributors

The original patch set was written by:

Jan Blunck
Miklos Szeredi
Bharata B Rao
David Woodhouse

More patches, testing, review, and suggestions came from:

Alexander Viro
Christoph Hellwig
Andy Whitcroft
Scott James Remnant
Sandu Popa Marius
Jan Rekorajski
J. R. Okajima
Erez Zadok
Trond Myklebust
J. Bruce Fields
David P. Quigley
Arnd Bergmann
Vladimir Dronnikov
Felix Fietkau

Thanks to everyone who contributed!

Other unioning file systems for Linux

A unioning file system is anything that attempts to merge the namespaces of two separate file systems. This is useful for things like sharing a read-only base file system between different clients, each of which has its own read-write file system layered on top. Many different implementations of unioning file systems exist, including union mounts and directories (namespace merging implemented at the VFS layer) and union(no -ing) file systems (namespace merging implemented in a file system below the VFS layer).

Here are some articles I wrote about unioning file systems:

Part 1: Unioning file systems: Architecture, features, and design choices

Part 2: Unioning file systems: Union directories and mounts

Part 3: Unioning file systems: unionfs and aufs