Lines Matching +full:s +full:- +full:merged
1 .. SPDX-License-Identifier: GPL-2.0
10 overlay-filesystem functionality in Linux (sometimes referred to as
11 union-filesystems). An overlay-filesystem tries to present a
17 ---------------
25 While directories will report an st_dev from the overlay-filesystem,
26 non-directory objects may report an st_dev from the lower filesystem or
29 over the lifetime of a non-directory object. Many applications and
48 feature with the "-o xino=on" overlay mount option. That is useful for the
60 +--------------+------------+------------+-----------------+----------------+
65 +--------------+-----+------+-----+------+--------+--------+--------+-------+
68 +--------------+-----+------+-----+------+--------+--------+--------+-------+
72 +--------------+-----+------+-----+------+--------+--------+--------+-------+
75 +--------------+-----+------+-----+------+--------+--------+--------+-------+
78 +--------------+-----+------+-----+------+--------+--------+--------+-------+
86 ---------------
88 An overlay filesystem combines two filesystems - an 'upper' filesystem
92 merged with the 'upper' object.
106 A read-only overlay of two read-only filesystems may use any
110 -----------
113 upper and lower filesystems and refers to a non-directory in either,
114 then the lower object is hidden - the name refers only to the upper
117 Where both upper and lower objects are directories, a merged directory
121 "upperdir" are combined into a merged directory:
123 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
124 workdir=/work /merged
129 Then whenever a lookup is requested in such a merged directory, the
132 actual lookups find directories, both are stored and a merged
136 Only the lists of names from directories are merged. Other content
141 --------------------------------
146 directories (non-directories are always opaque).
149 When a whiteout is found in the upper level of a merged directory, any
158 -------
160 When a 'readdir' request is made on a merged directory, the upper and
161 lower directories are each read and the name lists merged in the
162 obvious way (upper is read first, then lower - entries that already
163 exist are not re-added). This merged name list is cached in the
170 This means that changes to the merged directory do not appear while a
177 - read part of a directory
178 - remember an offset, and close the directory
179 - re-open the directory some time later
180 - seek to the remembered offset
186 Readdir on directories that are not merged is simply handled by the
190 --------------------
192 When renaming a directory that is on the lower layer or merged (i.e. the
211 - OVERLAY_FS_REDIRECT_DIR:
213 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:
221 - "redirect_dir=BOOL":
223 - "redirect_always_follow=BOOL":
225 - "redirect_max=NUM":
230 - "redirect_dir=on":
232 - "redirect_dir=follow":
234 - "redirect_dir=off":
237 - "redirect_dir=nofollow":
244 on the index entry. On lookup of a merged directory, if the upper
255 Non-directories
256 ---------------
258 Objects that are not directories (files, symlinks, device-special
261 the requires write-access, such as opening for write access, changing
263 to the upper filesystem (copy_up). Note that creating a hard-link
268 opened for read-write but the data is not modified.
271 exists in the upper filesystem - creating it and any parents as
273 mode, mtime, symlink-target etc.) and then if the object is a file, the
279 filesystem - future operations on the file are barely noticed by the
285 ----------------
293 3) non-mounting task MAY gain additional privileges through the overlay,
317 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
321 cp -a /lower /upper
322 mount --bind /upper /merged
325 the time of copy (on-demand vs. up-front).
329 ---------------------
334 mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
337 that case the overlay will be read-only.
345 ---------------------
375 --------------------------
415 Non-standard behavior
416 ---------------------
426 b) If a file residing on a lower layer is opened for read-only and then
438 If this feature is disabled, then rename(2) on a lower or merged directory
439 will fail with EXDEV ("Invalid cross-device link").
468 ---------------------------------
486 When the NFS export feature is enabled, a lookup of a merged directory,
492 will not be merged with the upper directory.
497 ----------
505 non-directory object, the index entry is a hard link to the upper inode.
513 1. For a non-upper object, encode a lower file handle from lower inode
515 3. For a pure-upper object and for an existing non-indexed upper object,
519 - Header including path type information (e.g. lower/upper)
520 - UUID of the underlying filesystem
521 - Underlying filesystem encoding of underlying inode
533 5. For a non-directory, instantiate a disconnected overlay dentry from the
538 Decoding a non-directory file handle may return a disconnected dentry.
555 The overlay filesystem does not support non-directory connectable file
564 read-write mount and will result in an error.
568 --------------
580 VFS. If any writeback error occurs on the upperdir's filesystem after a
595 ---------
597 There's a testsuite originally developed by David Howells and currently
600 https://github.com/amir73il/unionmount-testsuite.git
604 # cd unionmount-testsuite
605 # ./run --ov --verify