Merge tag 'armsoc-dt' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
[sfrench/cifs-2.6.git] / Documentation / filesystems / overlayfs.txt
1 Written by: Neil Brown
2 Please see MAINTAINERS file for where to send questions.
3
4 Overlay Filesystem
5 ==================
6
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.
12
13
14 Overlay objects
15 ---------------
16
17 The overlay filesystem approach is 'hybrid', because the objects that
18 appear in the filesystem do not always appear to belong to that filesystem.
19 In many 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).
22
23 While directories will report an st_dev from the overlay-filesystem,
24 non-directory objects may report an st_dev from the lower filesystem 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.
29
30 In the special case of all overlay layers on the same underlying
31 filesystem, all objects will report an st_dev from the overlay
32 filesystem and st_ino from the underlying filesystem.  This will
33 make the overlay mount more compliant with filesystem scanners and
34 overlay objects will be distinguishable from the corresponding
35 objects in the original filesystem.
36
37 On 64bit systems, even if all overlay layers are not on the same
38 underlying filesystem, the same compliant behavior could be achieved
39 with the "xino" feature.  The "xino" feature composes a unique object
40 identifier from the real object st_ino and an underlying fsid index.
41 If all underlying filesystems support NFS file handles and export file
42 handles with 32bit inode number encoding (e.g. ext4), overlay filesystem
43 will use the high inode number bits for fsid.  Even when the underlying
44 filesystem uses 64bit inode numbers, users can still enable the "xino"
45 feature with the "-o xino=on" overlay mount option.  That is useful for the
46 case of underlying filesystems like xfs and tmpfs, which use 64bit inode
47 numbers, but are very unlikely to use the high inode number bit.
48
49
50 Upper and Lower
51 ---------------
52
53 An overlay filesystem combines two filesystems - an 'upper' filesystem
54 and a 'lower' filesystem.  When a name exists in both filesystems, the
55 object in the 'upper' filesystem is visible while the object in the
56 'lower' filesystem is either hidden or, in the case of directories,
57 merged with the 'upper' object.
58
59 It would be more correct to refer to an upper and lower 'directory
60 tree' rather than 'filesystem' as it is quite possible for both
61 directory trees to be in the same filesystem and there is no
62 requirement that the root of a filesystem be given for either upper or
63 lower.
64
65 The lower filesystem can be any filesystem supported by Linux and does
66 not need to be writable.  The lower filesystem can even be another
67 overlayfs.  The upper filesystem will normally be writable and if it
68 is it must support the creation of trusted.* extended attributes, and
69 must provide valid d_type in readdir responses, so NFS is not suitable.
70
71 A read-only overlay of two read-only filesystems may use any
72 filesystem type.
73
74 Directories
75 -----------
76
77 Overlaying mainly involves directories.  If a given name appears in both
78 upper and lower filesystems and refers to a non-directory in either,
79 then the lower object is hidden - the name refers only to the upper
80 object.
81
82 Where both upper and lower objects are directories, a merged directory
83 is formed.
84
85 At mount time, the two directories given as mount options "lowerdir" and
86 "upperdir" are combined into a merged directory:
87
88   mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
89   workdir=/work /merged
90
91 The "workdir" needs to be an empty directory on the same filesystem
92 as upperdir.
93
94 Then whenever a lookup is requested in such a merged directory, the
95 lookup is performed in each actual directory and the combined result
96 is cached in the dentry belonging to the overlay filesystem.  If both
97 actual lookups find directories, both are stored and a merged
98 directory is created, otherwise only one is stored: the upper if it
99 exists, else the lower.
100
101 Only the lists of names from directories are merged.  Other content
102 such as metadata and extended attributes are reported for the upper
103 directory only.  These attributes of the lower directory are hidden.
104
105 whiteouts and opaque directories
106 --------------------------------
107
108 In order to support rm and rmdir without changing the lower
109 filesystem, an overlay filesystem needs to record in the upper filesystem
110 that files have been removed.  This is done using whiteouts and opaque
111 directories (non-directories are always opaque).
112
113 A whiteout is created as a character device with 0/0 device number.
114 When a whiteout is found in the upper level of a merged directory, any
115 matching name in the lower level is ignored, and the whiteout itself
116 is also hidden.
117
118 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
119 to "y".  Where the upper filesystem contains an opaque directory, any
120 directory in the lower filesystem with the same name is ignored.
121
122 readdir
123 -------
124
125 When a 'readdir' request is made on a merged directory, the upper and
126 lower directories are each read and the name lists merged in the
127 obvious way (upper is read first, then lower - entries that already
128 exist are not re-added).  This merged name list is cached in the
129 'struct file' and so remains as long as the file is kept open.  If the
130 directory is opened and read by two processes at the same time, they
131 will each have separate caches.  A seekdir to the start of the
132 directory (offset 0) followed by a readdir will cause the cache to be
133 discarded and rebuilt.
134
135 This means that changes to the merged directory do not appear while a
136 directory is being read.  This is unlikely to be noticed by many
137 programs.
138
139 seek offsets are assigned sequentially when the directories are read.
140 Thus if
141
142   - read part of a directory
143   - remember an offset, and close the directory
144   - re-open the directory some time later
145   - seek to the remembered offset
146
147 there may be little correlation between the old and new locations in
148 the list of filenames, particularly if anything has changed in the
149 directory.
150
151 Readdir on directories that are not merged is simply handled by the
152 underlying directory (upper or lower).
153
154 renaming directories
155 --------------------
156
157 When renaming a directory that is on the lower layer or merged (i.e. the
158 directory was not created on the upper layer to start with) overlayfs can
159 handle it in two different ways:
160
161 1. return EXDEV error: this error is returned by rename(2) when trying to
162    move a file or directory across filesystem boundaries.  Hence
163    applications are usually prepared to hande this error (mv(1) for example
164    recursively copies the directory tree).  This is the default behavior.
165
166 2. If the "redirect_dir" feature is enabled, then the directory will be
167    copied up (but not the contents).  Then the "trusted.overlay.redirect"
168    extended attribute is set to the path of the original location from the
169    root of the overlay.  Finally the directory is moved to the new
170    location.
171
172 There are several ways to tune the "redirect_dir" feature.
173
174 Kernel config options:
175
176 - OVERLAY_FS_REDIRECT_DIR:
177     If this is enabled, then redirect_dir is turned on by  default.
178 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:
179     If this is enabled, then redirects are always followed by default. Enabling
180     this results in a less secure configuration.  Enable this option only when
181     worried about backward compatibility with kernels that have the redirect_dir
182     feature and follow redirects even if turned off.
183
184 Module options (can also be changed through /sys/module/overlay/parameters/*):
185
186 - "redirect_dir=BOOL":
187     See OVERLAY_FS_REDIRECT_DIR kernel config option above.
188 - "redirect_always_follow=BOOL":
189     See OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW kernel config option above.
190 - "redirect_max=NUM":
191     The maximum number of bytes in an absolute redirect (default is 256).
192
193 Mount options:
194
195 - "redirect_dir=on":
196     Redirects are enabled.
197 - "redirect_dir=follow":
198     Redirects are not created, but followed.
199 - "redirect_dir=off":
200     Redirects are not created and only followed if "redirect_always_follow"
201     feature is enabled in the kernel/module config.
202 - "redirect_dir=nofollow":
203     Redirects are not created and not followed (equivalent to "redirect_dir=off"
204     if "redirect_always_follow" feature is not enabled).
205
206 When the NFS export feature is enabled, every copied up directory is
207 indexed by the file handle of the lower inode and a file handle of the
208 upper directory is stored in a "trusted.overlay.upper" extended attribute
209 on the index entry.  On lookup of a merged directory, if the upper
210 directory does not match the file handle stores in the index, that is an
211 indication that multiple upper directories may be redirected to the same
212 lower directory.  In that case, lookup returns an error and warns about
213 a possible inconsistency.
214
215 Because lower layer redirects cannot be verified with the index, enabling
216 NFS export support on an overlay filesystem with no upper layer requires
217 turning off redirect follow (e.g. "redirect_dir=nofollow").
218
219
220 Non-directories
221 ---------------
222
223 Objects that are not directories (files, symlinks, device-special
224 files etc.) are presented either from the upper or lower filesystem as
225 appropriate.  When a file in the lower filesystem is accessed in a way
226 the requires write-access, such as opening for write access, changing
227 some metadata etc., the file is first copied from the lower filesystem
228 to the upper filesystem (copy_up).  Note that creating a hard-link
229 also requires copy_up, though of course creation of a symlink does
230 not.
231
232 The copy_up may turn out to be unnecessary, for example if the file is
233 opened for read-write but the data is not modified.
234
235 The copy_up process first makes sure that the containing directory
236 exists in the upper filesystem - creating it and any parents as
237 necessary.  It then creates the object with the same metadata (owner,
238 mode, mtime, symlink-target etc.) and then if the object is a file, the
239 data is copied from the lower to the upper filesystem.  Finally any
240 extended attributes are copied up.
241
242 Once the copy_up is complete, the overlay filesystem simply
243 provides direct access to the newly created file in the upper
244 filesystem - future operations on the file are barely noticed by the
245 overlay filesystem (though an operation on the name of the file such as
246 rename or unlink will of course be noticed and handled).
247
248
249 Multiple lower layers
250 ---------------------
251
252 Multiple lower layers can now be given using the the colon (":") as a
253 separator character between the directory names.  For example:
254
255   mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
256
257 As the example shows, "upperdir=" and "workdir=" may be omitted.  In
258 that case the overlay will be read-only.
259
260 The specified lower directories will be stacked beginning from the
261 rightmost one and going left.  In the above example lower1 will be the
262 top, lower2 the middle and lower3 the bottom layer.
263
264
265 Metadata only copy up
266 --------------------
267
268 When metadata only copy up feature is enabled, overlayfs will only copy
269 up metadata (as opposed to whole file), when a metadata specific operation
270 like chown/chmod is performed. Full file will be copied up later when
271 file is opened for WRITE operation.
272
273 In other words, this is delayed data copy up operation and data is copied
274 up when there is a need to actually modify data.
275
276 There are multiple ways to enable/disable this feature. A config option
277 CONFIG_OVERLAY_FS_METACOPY can be set/unset to enable/disable this feature
278 by default. Or one can enable/disable it at module load time with module
279 parameter metacopy=on/off. Lastly, there is also a per mount option
280 metacopy=on/off to enable/disable this feature per mount.
281
282 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
283 it is possible that an attacker can create a handcrafted file with
284 appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
285 pointed by REDIRECT. This should not be possible on local system as setting
286 "trusted." xattrs will require CAP_SYS_ADMIN. But it should be possible
287 for untrusted layers like from a pen drive.
288
289 Note: redirect_dir={off|nofollow|follow(*)} conflicts with metacopy=on, and
290 results in an error.
291
292 (*) redirect_dir=follow only conflicts with metacopy=on if upperdir=... is
293 given.
294
295 Sharing and copying layers
296 --------------------------
297
298 Lower layers may be shared among several overlay mounts and that is indeed
299 a very common practice.  An overlay mount may use the same lower layer
300 path as another overlay mount and it may use a lower layer path that is
301 beneath or above the path of another overlay lower layer path.
302
303 Using an upper layer path and/or a workdir path that are already used by
304 another overlay mount is not allowed and may fail with EBUSY.  Using
305 partially overlapping paths is not allowed but will not fail with EBUSY.
306 If files are accessed from two overlayfs mounts which share or overlap the
307 upper layer and/or workdir path the behavior of the overlay is undefined,
308 though it will not result in a crash or deadlock.
309
310 Mounting an overlay using an upper layer path, where the upper layer path
311 was previously used by another mounted overlay in combination with a
312 different lower layer path, is allowed, unless the "inodes index" feature
313 or "metadata only copy up" feature is enabled.
314
315 With the "inodes index" feature, on the first time mount, an NFS file
316 handle of the lower layer root directory, along with the UUID of the lower
317 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
318 attribute on the upper layer root directory.  On subsequent mount attempts,
319 the lower root directory file handle and lower filesystem UUID are compared
320 to the stored origin in upper root directory.  On failure to verify the
321 lower root origin, mount will fail with ESTALE.  An overlayfs mount with
322 "inodes index" enabled will fail with EOPNOTSUPP if the lower filesystem
323 does not support NFS export, lower filesystem does not have a valid UUID or
324 if the upper filesystem does not support extended attributes.
325
326 For "metadata only copy up" feature there is no verification mechanism at
327 mount time. So if same upper is mounted with different set of lower, mount
328 probably will succeed but expect the unexpected later on. So don't do it.
329
330 It is quite a common practice to copy overlay layers to a different
331 directory tree on the same or different underlying filesystem, and even
332 to a different machine.  With the "inodes index" feature, trying to mount
333 the copied layers will fail the verification of the lower root file handle.
334
335
336 Non-standard behavior
337 ---------------------
338
339 Overlayfs can now act as a POSIX compliant filesystem with the following
340 features turned on:
341
342 1) "redirect_dir"
343
344 Enabled with the mount option or module option: "redirect_dir=on" or with
345 the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
346
347 If this feature is disabled, then rename(2) on a lower or merged directory
348 will fail with EXDEV ("Invalid cross-device link").
349
350 2) "inode index"
351
352 Enabled with the mount option or module option "index=on" or with the
353 kernel config option CONFIG_OVERLAY_FS_INDEX=y.
354
355 If this feature is disabled and a file with multiple hard links is copied
356 up, then this will "break" the link.  Changes will not be propagated to
357 other names referring to the same inode.
358
359 3) "xino"
360
361 Enabled with the mount option "xino=auto" or "xino=on", with the module
362 option "xino_auto=on" or with the kernel config option
363 CONFIG_OVERLAY_FS_XINO_AUTO=y.  Also implicitly enabled by using the same
364 underlying filesystem for all layers making up the overlay.
365
366 If this feature is disabled or the underlying filesystem doesn't have
367 enough free bits in the inode number, then overlayfs will not be able to
368 guarantee that the values of st_ino and st_dev returned by stat(2) and the
369 value of d_ino returned by readdir(3) will act like on a normal filesystem.
370 E.g. the value of st_dev may be different for two objects in the same
371 overlay filesystem and the value of st_ino for directory objects may not be
372 persistent and could change even while the overlay filesystem is mounted.
373
374
375 Changes to underlying filesystems
376 ---------------------------------
377
378 Offline changes, when the overlay is not mounted, are allowed to either
379 the upper or the lower trees.
380
381 Changes to the underlying filesystems while part of a mounted overlay
382 filesystem are not allowed.  If the underlying filesystem is changed,
383 the behavior of the overlay is undefined, though it will not result in
384 a crash or deadlock.
385
386 When the overlay NFS export feature is enabled, overlay filesystems
387 behavior on offline changes of the underlying lower layer is different
388 than the behavior when NFS export is disabled.
389
390 On every copy_up, an NFS file handle of the lower inode, along with the
391 UUID of the lower filesystem, are encoded and stored in an extended
392 attribute "trusted.overlay.origin" on the upper inode.
393
394 When the NFS export feature is enabled, a lookup of a merged directory,
395 that found a lower directory at the lookup path or at the path pointed
396 to by the "trusted.overlay.redirect" extended attribute, will verify
397 that the found lower directory file handle and lower filesystem UUID
398 match the origin file handle that was stored at copy_up time.  If a
399 found lower directory does not match the stored origin, that directory
400 will not be merged with the upper directory.
401
402
403
404 NFS export
405 ----------
406
407 When the underlying filesystems supports NFS export and the "nfs_export"
408 feature is enabled, an overlay filesystem may be exported to NFS.
409
410 With the "nfs_export" feature, on copy_up of any lower object, an index
411 entry is created under the index directory.  The index entry name is the
412 hexadecimal representation of the copy up origin file handle.  For a
413 non-directory object, the index entry is a hard link to the upper inode.
414 For a directory object, the index entry has an extended attribute
415 "trusted.overlay.upper" with an encoded file handle of the upper
416 directory inode.
417
418 When encoding a file handle from an overlay filesystem object, the
419 following rules apply:
420
421 1. For a non-upper object, encode a lower file handle from lower inode
422 2. For an indexed object, encode a lower file handle from copy_up origin
423 3. For a pure-upper object and for an existing non-indexed upper object,
424    encode an upper file handle from upper inode
425
426 The encoded overlay file handle includes:
427  - Header including path type information (e.g. lower/upper)
428  - UUID of the underlying filesystem
429  - Underlying filesystem encoding of underlying inode
430
431 This encoding format is identical to the encoding format file handles that
432 are stored in extended attribute "trusted.overlay.origin".
433
434 When decoding an overlay file handle, the following steps are followed:
435
436 1. Find underlying layer by UUID and path type information.
437 2. Decode the underlying filesystem file handle to underlying dentry.
438 3. For a lower file handle, lookup the handle in index directory by name.
439 4. If a whiteout is found in index, return ESTALE. This represents an
440    overlay object that was deleted after its file handle was encoded.
441 5. For a non-directory, instantiate a disconnected overlay dentry from the
442    decoded underlying dentry, the path type and index inode, if found.
443 6. For a directory, use the connected underlying decoded dentry, path type
444    and index, to lookup a connected overlay dentry.
445
446 Decoding a non-directory file handle may return a disconnected dentry.
447 copy_up of that disconnected dentry will create an upper index entry with
448 no upper alias.
449
450 When overlay filesystem has multiple lower layers, a middle layer
451 directory may have a "redirect" to lower directory.  Because middle layer
452 "redirects" are not indexed, a lower file handle that was encoded from the
453 "redirect" origin directory, cannot be used to find the middle or upper
454 layer directory.  Similarly, a lower file handle that was encoded from a
455 descendant of the "redirect" origin directory, cannot be used to
456 reconstruct a connected overlay path.  To mitigate the cases of
457 directories that cannot be decoded from a lower file handle, these
458 directories are copied up on encode and encoded as an upper file handle.
459 On an overlay filesystem with no upper layer this mitigation cannot be
460 used NFS export in this setup requires turning off redirect follow (e.g.
461 "redirect_dir=nofollow").
462
463 The overlay filesystem does not support non-directory connectable file
464 handles, so exporting with the 'subtree_check' exportfs configuration will
465 cause failures to lookup files over NFS.
466
467 When the NFS export feature is enabled, all directory index entries are
468 verified on mount time to check that upper file handles are not stale.
469 This verification may cause significant overhead in some cases.
470
471
472 Testsuite
473 ---------
474
475 There's a testsuite originally developed by David Howells and currently
476 maintained by Amir Goldstein at:
477
478   https://github.com/amir73il/unionmount-testsuite.git
479
480 Run as root:
481
482   # cd unionmount-testsuite
483   # ./run --ov --verify