About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / overlayfs.txt

Custom Search

Based on kernel version 4.9. Page generated on 2016-12-21 14:34 EST.

1	Written by: Neil Brown
2	Please see MAINTAINERS file for where to send questions.
4	Overlay Filesystem
5	==================
7	This document describes a prototype for a new approach to providing
8	overlay-filesystem functionality in Linux (sometimes referred to as
9	union-filesystems).  An overlay-filesystem tries to present a
10	filesystem which is the result over overlaying one filesystem on top
11	of the other.
13	The result will inevitably fail to look exactly like a normal
14	filesystem for various technical reasons.  The expectation is that
15	many use cases will be able to ignore these differences.
17	This approach is 'hybrid' because the objects that appear in the
18	filesystem do not all appear to belong to that filesystem.  In many
19	cases an object accessed in the union will be indistinguishable
20	from accessing the corresponding object from the original filesystem.
21	This is most obvious from the 'st_dev' field returned by stat(2).
23	While directories will report an st_dev from the overlay-filesystem,
24	all non-directory objects will report an st_dev from the lower or
25	upper filesystem that is providing the object.  Similarly st_ino will
26	only be unique when combined with st_dev, and both of these can change
27	over the lifetime of a non-directory object.  Many applications and
28	tools ignore these values and will not be affected.
30	Upper and Lower
31	---------------
33	An overlay filesystem combines two filesystems - an 'upper' filesystem
34	and a 'lower' filesystem.  When a name exists in both filesystems, the
35	object in the 'upper' filesystem is visible while the object in the
36	'lower' filesystem is either hidden or, in the case of directories,
37	merged with the 'upper' object.
39	It would be more correct to refer to an upper and lower 'directory
40	tree' rather than 'filesystem' as it is quite possible for both
41	directory trees to be in the same filesystem and there is no
42	requirement that the root of a filesystem be given for either upper or
43	lower.
45	The lower filesystem can be any filesystem supported by Linux and does
46	not need to be writable.  The lower filesystem can even be another
47	overlayfs.  The upper filesystem will normally be writable and if it
48	is it must support the creation of trusted.* extended attributes, and
49	must provide valid d_type in readdir responses, so NFS is not suitable.
51	A read-only overlay of two read-only filesystems may use any
52	filesystem type.
54	Directories
55	-----------
57	Overlaying mainly involves directories.  If a given name appears in both
58	upper and lower filesystems and refers to a non-directory in either,
59	then the lower object is hidden - the name refers only to the upper
60	object.
62	Where both upper and lower objects are directories, a merged directory
63	is formed.
65	At mount time, the two directories given as mount options "lowerdir" and
66	"upperdir" are combined into a merged directory:
68	  mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
69	workdir=/work /merged
71	The "workdir" needs to be an empty directory on the same filesystem
72	as upperdir.
74	Then whenever a lookup is requested in such a merged directory, the
75	lookup is performed in each actual directory and the combined result
76	is cached in the dentry belonging to the overlay filesystem.  If both
77	actual lookups find directories, both are stored and a merged
78	directory is created, otherwise only one is stored: the upper if it
79	exists, else the lower.
81	Only the lists of names from directories are merged.  Other content
82	such as metadata and extended attributes are reported for the upper
83	directory only.  These attributes of the lower directory are hidden.
85	whiteouts and opaque directories
86	--------------------------------
88	In order to support rm and rmdir without changing the lower
89	filesystem, an overlay filesystem needs to record in the upper filesystem
90	that files have been removed.  This is done using whiteouts and opaque
91	directories (non-directories are always opaque).
93	A whiteout is created as a character device with 0/0 device number.
94	When a whiteout is found in the upper level of a merged directory, any
95	matching name in the lower level is ignored, and the whiteout itself
96	is also hidden.
98	A directory is made opaque by setting the xattr "trusted.overlay.opaque"
99	to "y".  Where the upper filesystem contains an opaque directory, any
100	directory in the lower filesystem with the same name is ignored.
102	readdir
103	-------
105	When a 'readdir' request is made on a merged directory, the upper and
106	lower directories are each read and the name lists merged in the
107	obvious way (upper is read first, then lower - entries that already
108	exist are not re-added).  This merged name list is cached in the
109	'struct file' and so remains as long as the file is kept open.  If the
110	directory is opened and read by two processes at the same time, they
111	will each have separate caches.  A seekdir to the start of the
112	directory (offset 0) followed by a readdir will cause the cache to be
113	discarded and rebuilt.
115	This means that changes to the merged directory do not appear while a
116	directory is being read.  This is unlikely to be noticed by many
117	programs.
119	seek offsets are assigned sequentially when the directories are read.
120	Thus if
121	  - read part of a directory
122	  - remember an offset, and close the directory
123	  - re-open the directory some time later
124	  - seek to the remembered offset
126	there may be little correlation between the old and new locations in
127	the list of filenames, particularly if anything has changed in the
128	directory.
130	Readdir on directories that are not merged is simply handled by the
131	underlying directory (upper or lower).
134	Non-directories
135	---------------
137	Objects that are not directories (files, symlinks, device-special
138	files etc.) are presented either from the upper or lower filesystem as
139	appropriate.  When a file in the lower filesystem is accessed in a way
140	the requires write-access, such as opening for write access, changing
141	some metadata etc., the file is first copied from the lower filesystem
142	to the upper filesystem (copy_up).  Note that creating a hard-link
143	also requires copy_up, though of course creation of a symlink does
144	not.
146	The copy_up may turn out to be unnecessary, for example if the file is
147	opened for read-write but the data is not modified.
149	The copy_up process first makes sure that the containing directory
150	exists in the upper filesystem - creating it and any parents as
151	necessary.  It then creates the object with the same metadata (owner,
152	mode, mtime, symlink-target etc.) and then if the object is a file, the
153	data is copied from the lower to the upper filesystem.  Finally any
154	extended attributes are copied up.
156	Once the copy_up is complete, the overlay filesystem simply
157	provides direct access to the newly created file in the upper
158	filesystem - future operations on the file are barely noticed by the
159	overlay filesystem (though an operation on the name of the file such as
160	rename or unlink will of course be noticed and handled).
163	Multiple lower layers
164	---------------------
166	Multiple lower layers can now be given using the the colon (":") as a
167	separator character between the directory names.  For example:
169	  mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
171	As the example shows, "upperdir=" and "workdir=" may be omitted.  In
172	that case the overlay will be read-only.
174	The specified lower directories will be stacked beginning from the
175	rightmost one and going left.  In the above example lower1 will be the
176	top, lower2 the middle and lower3 the bottom layer.
179	Non-standard behavior
180	---------------------
182	The copy_up operation essentially creates a new, identical file and
183	moves it over to the old name.  The new file may be on a different
184	filesystem, so both st_dev and st_ino of the file may change.
186	Any open files referring to this inode will access the old data.
188	Any file locks (and leases) obtained before copy_up will not apply
189	to the copied up file.
191	If a file with multiple hard links is copied up, then this will
192	"break" the link.  Changes will not be propagated to other names
193	referring to the same inode.
195	Changes to underlying filesystems
196	---------------------------------
198	Offline changes, when the overlay is not mounted, are allowed to either
199	the upper or the lower trees.
201	Changes to the underlying filesystems while part of a mounted overlay
202	filesystem are not allowed.  If the underlying filesystem is changed,
203	the behavior of the overlay is undefined, though it will not result in
204	a crash or deadlock.
206	Testsuite
207	---------
209	There's testsuite developed by David Howells at:
211	  git://git.infradead.org/users/dhowells/unionmount-testsuite.git
213	Run as root:
215	  # cd unionmount-testsuite
216	  # ./run --ov
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.