linux-imx

Written by: Neil Brown

Please see MAINTAINERS file for where to send questions.

​

Overlay Filesystem

==================

​

This document describes a prototype for a new approach to providing

overlay-filesystem functionality in Linux (sometimes referred to as

union-filesystems).  An overlay-filesystem tries to present a

filesystem which is the result over overlaying one filesystem on top

of the other.

​

​

Overlay objects

---------------

​

The overlay filesystem approach is 'hybrid', because the objects that

appear in the filesystem do not always appear to belong to that filesystem.

In many cases, an object accessed in the union will be indistinguishable

from accessing the corresponding object from the original filesystem.

This is most obvious from the 'st_dev' field returned by stat(2).

​

While directories will report an st_dev from the overlay-filesystem,

non-directory objects may report an st_dev from the lower filesystem or

upper filesystem that is providing the object.  Similarly st_ino will

only be unique when combined with st_dev, and both of these can change

over the lifetime of a non-directory object.  Many applications and

tools ignore these values and will not be affected.

​

In the special case of all overlay layers on the same underlying

filesystem, all objects will report an st_dev from the overlay

filesystem and st_ino from the underlying filesystem.  This will

make the overlay mount more compliant with filesystem scanners and

overlay objects will be distinguishable from the corresponding

objects in the original filesystem.

​

On 64bit systems, even if all overlay layers are not on the same

underlying filesystem, the same compliant behavior could be achieved

with the "xino" feature.  The "xino" feature composes a unique object

identifier from the real object st_ino and an underlying fsid index.

If all underlying filesystems support NFS file handles and export file

handles with 32bit inode number encoding (e.g. ext4), overlay filesystem

will use the high inode number bits for fsid.  Even when the underlying

filesystem uses 64bit inode numbers, users can still enable the "xino"

feature with the "-o xino=on" overlay mount option.  That is useful for the

case of underlying filesystems like xfs and tmpfs, which use 64bit inode

numbers, but are very unlikely to use the high inode number bit.

​

​

Upper and Lower

---------------

​

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.

​

Directories

-----------

​

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 overlay overlay -olowerdir=/lower,upperdir=/upper,\

  workdir=/work /merged

​

The "workdir" needs to be an empty directory on the same filesystem

as upperdir.