1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Written by: Neil Brown 3 Written by: Neil Brown
4 Please see MAINTAINERS file for where to send 4 Please see MAINTAINERS file for where to send questions.
5 5
6 Overlay Filesystem 6 Overlay Filesystem
7 ================== 7 ==================
8 8
9 This document describes a prototype for a new 9 This document describes a prototype for a new approach to providing
10 overlay-filesystem functionality in Linux (som 10 overlay-filesystem functionality in Linux (sometimes referred to as
11 union-filesystems). An overlay-filesystem tri 11 union-filesystems). An overlay-filesystem tries to present a
12 filesystem which is the result over overlaying 12 filesystem which is the result over overlaying one filesystem on top
13 of the other. 13 of the other.
14 14
15 15
16 Overlay objects 16 Overlay objects
17 --------------- 17 ---------------
18 18
19 The overlay filesystem approach is 'hybrid', b 19 The overlay filesystem approach is 'hybrid', because the objects that
20 appear in the filesystem do not always appear 20 appear in the filesystem do not always appear to belong to that filesystem.
21 In many cases, an object accessed in the union 21 In many cases, an object accessed in the union will be indistinguishable
22 from accessing the corresponding object from t 22 from accessing the corresponding object from the original filesystem.
23 This is most obvious from the 'st_dev' field r 23 This is most obvious from the 'st_dev' field returned by stat(2).
24 24
25 While directories will report an st_dev from t 25 While directories will report an st_dev from the overlay-filesystem,
26 non-directory objects may report an st_dev fro 26 non-directory objects may report an st_dev from the lower filesystem or
27 upper filesystem that is providing the object. 27 upper filesystem that is providing the object. Similarly st_ino will
28 only be unique when combined with st_dev, and 28 only be unique when combined with st_dev, and both of these can change
29 over the lifetime of a non-directory object. 29 over the lifetime of a non-directory object. Many applications and
30 tools ignore these values and will not be affe 30 tools ignore these values and will not be affected.
31 31
32 In the special case of all overlay layers on t 32 In the special case of all overlay layers on the same underlying
33 filesystem, all objects will report an st_dev 33 filesystem, all objects will report an st_dev from the overlay
34 filesystem and st_ino from the underlying file 34 filesystem and st_ino from the underlying filesystem. This will
35 make the overlay mount more compliant with fil 35 make the overlay mount more compliant with filesystem scanners and
36 overlay objects will be distinguishable from t 36 overlay objects will be distinguishable from the corresponding
37 objects in the original filesystem. 37 objects in the original filesystem.
38 38
39 On 64bit systems, even if all overlay layers a 39 On 64bit systems, even if all overlay layers are not on the same
40 underlying filesystem, the same compliant beha 40 underlying filesystem, the same compliant behavior could be achieved
41 with the "xino" feature. The "xino" feature c 41 with the "xino" feature. The "xino" feature composes a unique object
42 identifier from the real object st_ino and an 42 identifier from the real object st_ino and an underlying fsid number.
43 The "xino" feature uses the high inode number 43 The "xino" feature uses the high inode number bits for fsid, because the
44 underlying filesystems rarely use the high ino 44 underlying filesystems rarely use the high inode number bits. In case
45 the underlying inode number does overflow into 45 the underlying inode number does overflow into the high xino bits, overlay
46 filesystem will fall back to the non xino beha 46 filesystem will fall back to the non xino behavior for that inode.
47 47
48 The "xino" feature can be enabled with the "-o 48 The "xino" feature can be enabled with the "-o xino=on" overlay mount option.
49 If all underlying filesystems support NFS file 49 If all underlying filesystems support NFS file handles, the value of st_ino
50 for overlay filesystem objects is not only uni 50 for overlay filesystem objects is not only unique, but also persistent over
51 the lifetime of the filesystem. The "-o xino= 51 the lifetime of the filesystem. The "-o xino=auto" overlay mount option
52 enables the "xino" feature only if the persist 52 enables the "xino" feature only if the persistent st_ino requirement is met.
53 53
54 The following table summarizes what can be exp 54 The following table summarizes what can be expected in different overlay
55 configurations. 55 configurations.
56 56
57 Inode properties 57 Inode properties
58 ```````````````` 58 ````````````````
59 59
60 +--------------+------------+------------+---- 60 +--------------+------------+------------+-----------------+----------------+
61 |Configuration | Persistent | Uniform | st_ 61 |Configuration | Persistent | Uniform | st_ino == d_ino | d_ino == i_ino |
62 | | st_ino | st_dev | 62 | | st_ino | st_dev | | [*] |
63 +==============+=====+======+=====+======+==== 63 +==============+=====+======+=====+======+========+========+========+=======+
64 | | dir | !dir | dir | !dir | di 64 | | dir | !dir | dir | !dir | dir + !dir | dir | !dir |
65 +--------------+-----+------+-----+------+---- 65 +--------------+-----+------+-----+------+--------+--------+--------+-------+
66 | All layers | Y | Y | Y | Y | Y 66 | All layers | Y | Y | Y | Y | Y | Y | Y | Y |
67 | on same fs | | | | | 67 | on same fs | | | | | | | | |
68 +--------------+-----+------+-----+------+---- 68 +--------------+-----+------+-----+------+--------+--------+--------+-------+
69 | Layers not | N | N | Y | N | N 69 | Layers not | N | N | Y | N | N | Y | N | Y |
70 | on same fs, | | | | | 70 | on same fs, | | | | | | | | |
71 | xino=off | | | | | 71 | xino=off | | | | | | | | |
72 +--------------+-----+------+-----+------+---- 72 +--------------+-----+------+-----+------+--------+--------+--------+-------+
73 | xino=on/auto | Y | Y | Y | Y | Y 73 | xino=on/auto | Y | Y | Y | Y | Y | Y | Y | Y |
74 +--------------+-----+------+-----+------+---- 74 +--------------+-----+------+-----+------+--------+--------+--------+-------+
75 | xino=on/auto,| N | N | Y | N | N 75 | xino=on/auto,| N | N | Y | N | N | Y | N | Y |
76 | ino overflow | | | | | 76 | ino overflow | | | | | | | | |
77 +--------------+-----+------+-----+------+---- 77 +--------------+-----+------+-----+------+--------+--------+--------+-------+
78 78
79 [*] nfsd v3 readdirplus verifies d_ino == i_in 79 [*] nfsd v3 readdirplus verifies d_ino == i_ino. i_ino is exposed via several
80 /proc files, such as /proc/locks and /proc/sel 80 /proc files, such as /proc/locks and /proc/self/fdinfo/<fd> of an inotify
81 file descriptor. 81 file descriptor.
82 82
83 Upper and Lower 83 Upper and Lower
84 --------------- 84 ---------------
85 85
86 An overlay filesystem combines two filesystems 86 An overlay filesystem combines two filesystems - an 'upper' filesystem
87 and a 'lower' filesystem. When a name exists 87 and a 'lower' filesystem. When a name exists in both filesystems, the
88 object in the 'upper' filesystem is visible wh 88 object in the 'upper' filesystem is visible while the object in the
89 'lower' filesystem is either hidden or, in the 89 'lower' filesystem is either hidden or, in the case of directories,
90 merged with the 'upper' object. 90 merged with the 'upper' object.
91 91
92 It would be more correct to refer to an upper 92 It would be more correct to refer to an upper and lower 'directory
93 tree' rather than 'filesystem' as it is quite 93 tree' rather than 'filesystem' as it is quite possible for both
94 directory trees to be in the same filesystem a 94 directory trees to be in the same filesystem and there is no
95 requirement that the root of a filesystem be g 95 requirement that the root of a filesystem be given for either upper or
96 lower. 96 lower.
97 97
98 A wide range of filesystems supported by Linux 98 A wide range of filesystems supported by Linux can be the lower filesystem,
99 but not all filesystems that are mountable by 99 but not all filesystems that are mountable by Linux have the features
100 needed for OverlayFS to work. The lower files 100 needed for OverlayFS to work. The lower filesystem does not need to be
101 writable. The lower filesystem can even be an 101 writable. The lower filesystem can even be another overlayfs. The upper
102 filesystem will normally be writable and if it 102 filesystem will normally be writable and if it is it must support the
103 creation of trusted.* and/or user.* extended a 103 creation of trusted.* and/or user.* extended attributes, and must provide
104 valid d_type in readdir responses, so NFS is n 104 valid d_type in readdir responses, so NFS is not suitable.
105 105
106 A read-only overlay of two read-only filesyste 106 A read-only overlay of two read-only filesystems may use any
107 filesystem type. 107 filesystem type.
108 108
109 Directories 109 Directories
110 ----------- 110 -----------
111 111
112 Overlaying mainly involves directories. If a 112 Overlaying mainly involves directories. If a given name appears in both
113 upper and lower filesystems and refers to a no 113 upper and lower filesystems and refers to a non-directory in either,
114 then the lower object is hidden - the name ref 114 then the lower object is hidden - the name refers only to the upper
115 object. 115 object.
116 116
117 Where both upper and lower objects are directo 117 Where both upper and lower objects are directories, a merged directory
118 is formed. 118 is formed.
119 119
120 At mount time, the two directories given as mo 120 At mount time, the two directories given as mount options "lowerdir" and
121 "upperdir" are combined into a merged director 121 "upperdir" are combined into a merged directory::
122 122
123 mount -t overlay overlay -olowerdir=/lower,u 123 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
124 workdir=/work /merged 124 workdir=/work /merged
125 125
126 The "workdir" needs to be an empty directory o 126 The "workdir" needs to be an empty directory on the same filesystem
127 as upperdir. 127 as upperdir.
128 128
129 Then whenever a lookup is requested in such a 129 Then whenever a lookup is requested in such a merged directory, the
130 lookup is performed in each actual directory a 130 lookup is performed in each actual directory and the combined result
131 is cached in the dentry belonging to the overl 131 is cached in the dentry belonging to the overlay filesystem. If both
132 actual lookups find directories, both are stor 132 actual lookups find directories, both are stored and a merged
133 directory is created, otherwise only one is st 133 directory is created, otherwise only one is stored: the upper if it
134 exists, else the lower. 134 exists, else the lower.
135 135
136 Only the lists of names from directories are m 136 Only the lists of names from directories are merged. Other content
137 such as metadata and extended attributes are r 137 such as metadata and extended attributes are reported for the upper
138 directory only. These attributes of the lower 138 directory only. These attributes of the lower directory are hidden.
139 139
140 whiteouts and opaque directories 140 whiteouts and opaque directories
141 -------------------------------- 141 --------------------------------
142 142
143 In order to support rm and rmdir without chang 143 In order to support rm and rmdir without changing the lower
144 filesystem, an overlay filesystem needs to rec 144 filesystem, an overlay filesystem needs to record in the upper filesystem
145 that files have been removed. This is done us 145 that files have been removed. This is done using whiteouts and opaque
146 directories (non-directories are always opaque 146 directories (non-directories are always opaque).
147 147
148 A whiteout is created as a character device wi 148 A whiteout is created as a character device with 0/0 device number or
149 as a zero-size regular file with the xattr "tr 149 as a zero-size regular file with the xattr "trusted.overlay.whiteout".
150 150
151 When a whiteout is found in the upper level of 151 When a whiteout is found in the upper level of a merged directory, any
152 matching name in the lower level is ignored, a 152 matching name in the lower level is ignored, and the whiteout itself
153 is also hidden. 153 is also hidden.
154 154
155 A directory is made opaque by setting the xatt 155 A directory is made opaque by setting the xattr "trusted.overlay.opaque"
156 to "y". Where the upper filesystem contains a 156 to "y". Where the upper filesystem contains an opaque directory, any
157 directory in the lower filesystem with the sam 157 directory in the lower filesystem with the same name is ignored.
158 158
159 An opaque directory should not conntain any wh 159 An opaque directory should not conntain any whiteouts, because they do not
160 serve any purpose. A merge directory containi 160 serve any purpose. A merge directory containing regular files with the xattr
161 "trusted.overlay.whiteout", should be addition 161 "trusted.overlay.whiteout", should be additionally marked by setting the xattr
162 "trusted.overlay.opaque" to "x" on the merge d 162 "trusted.overlay.opaque" to "x" on the merge directory itself.
163 This is needed to avoid the overhead of checki 163 This is needed to avoid the overhead of checking the "trusted.overlay.whiteout"
164 on all entries during readdir in the common ca 164 on all entries during readdir in the common case.
165 165
166 readdir 166 readdir
167 ------- 167 -------
168 168
169 When a 'readdir' request is made on a merged d 169 When a 'readdir' request is made on a merged directory, the upper and
170 lower directories are each read and the name l 170 lower directories are each read and the name lists merged in the
171 obvious way (upper is read first, then lower - 171 obvious way (upper is read first, then lower - entries that already
172 exist are not re-added). This merged name lis 172 exist are not re-added). This merged name list is cached in the
173 'struct file' and so remains as long as the fi 173 'struct file' and so remains as long as the file is kept open. If the
174 directory is opened and read by two processes 174 directory is opened and read by two processes at the same time, they
175 will each have separate caches. A seekdir to 175 will each have separate caches. A seekdir to the start of the
176 directory (offset 0) followed by a readdir wil 176 directory (offset 0) followed by a readdir will cause the cache to be
177 discarded and rebuilt. 177 discarded and rebuilt.
178 178
179 This means that changes to the merged director 179 This means that changes to the merged directory do not appear while a
180 directory is being read. This is unlikely to 180 directory is being read. This is unlikely to be noticed by many
181 programs. 181 programs.
182 182
183 seek offsets are assigned sequentially when th 183 seek offsets are assigned sequentially when the directories are read.
184 Thus if: 184 Thus if:
185 185
186 - read part of a directory 186 - read part of a directory
187 - remember an offset, and close the directory 187 - remember an offset, and close the directory
188 - re-open the directory some time later 188 - re-open the directory some time later
189 - seek to the remembered offset 189 - seek to the remembered offset
190 190
191 there may be little correlation between the ol 191 there may be little correlation between the old and new locations in
192 the list of filenames, particularly if anythin 192 the list of filenames, particularly if anything has changed in the
193 directory. 193 directory.
194 194
195 Readdir on directories that are not merged is 195 Readdir on directories that are not merged is simply handled by the
196 underlying directory (upper or lower). 196 underlying directory (upper or lower).
197 197
198 renaming directories 198 renaming directories
199 -------------------- 199 --------------------
200 200
201 When renaming a directory that is on the lower 201 When renaming a directory that is on the lower layer or merged (i.e. the
202 directory was not created on the upper layer t 202 directory was not created on the upper layer to start with) overlayfs can
203 handle it in two different ways: 203 handle it in two different ways:
204 204
205 1. return EXDEV error: this error is returned 205 1. return EXDEV error: this error is returned by rename(2) when trying to
206 move a file or directory across filesystem 206 move a file or directory across filesystem boundaries. Hence
207 applications are usually prepared to handle 207 applications are usually prepared to handle this error (mv(1) for example
208 recursively copies the directory tree). Th 208 recursively copies the directory tree). This is the default behavior.
209 209
210 2. If the "redirect_dir" feature is enabled, t 210 2. If the "redirect_dir" feature is enabled, then the directory will be
211 copied up (but not the contents). Then the 211 copied up (but not the contents). Then the "trusted.overlay.redirect"
212 extended attribute is set to the path of th 212 extended attribute is set to the path of the original location from the
213 root of the overlay. Finally the directory 213 root of the overlay. Finally the directory is moved to the new
214 location. 214 location.
215 215
216 There are several ways to tune the "redirect_d 216 There are several ways to tune the "redirect_dir" feature.
217 217
218 Kernel config options: 218 Kernel config options:
219 219
220 - OVERLAY_FS_REDIRECT_DIR: 220 - OVERLAY_FS_REDIRECT_DIR:
221 If this is enabled, then redirect_dir is t 221 If this is enabled, then redirect_dir is turned on by default.
222 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW: 222 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:
223 If this is enabled, then redirects are alw 223 If this is enabled, then redirects are always followed by default. Enabling
224 this results in a less secure configuratio 224 this results in a less secure configuration. Enable this option only when
225 worried about backward compatibility with 225 worried about backward compatibility with kernels that have the redirect_dir
226 feature and follow redirects even if turne 226 feature and follow redirects even if turned off.
227 227
228 Module options (can also be changed through /s 228 Module options (can also be changed through /sys/module/overlay/parameters/):
229 229
230 - "redirect_dir=BOOL": 230 - "redirect_dir=BOOL":
231 See OVERLAY_FS_REDIRECT_DIR kernel config 231 See OVERLAY_FS_REDIRECT_DIR kernel config option above.
232 - "redirect_always_follow=BOOL": 232 - "redirect_always_follow=BOOL":
233 See OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW kern 233 See OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW kernel config option above.
234 - "redirect_max=NUM": 234 - "redirect_max=NUM":
235 The maximum number of bytes in an absolute 235 The maximum number of bytes in an absolute redirect (default is 256).
236 236
237 Mount options: 237 Mount options:
238 238
239 - "redirect_dir=on": 239 - "redirect_dir=on":
240 Redirects are enabled. 240 Redirects are enabled.
241 - "redirect_dir=follow": 241 - "redirect_dir=follow":
242 Redirects are not created, but followed. 242 Redirects are not created, but followed.
243 - "redirect_dir=nofollow": 243 - "redirect_dir=nofollow":
244 Redirects are not created and not followed 244 Redirects are not created and not followed.
245 - "redirect_dir=off": 245 - "redirect_dir=off":
246 If "redirect_always_follow" is enabled in 246 If "redirect_always_follow" is enabled in the kernel/module config,
247 this "off" translates to "follow", otherwi 247 this "off" translates to "follow", otherwise it translates to "nofollow".
248 248
249 When the NFS export feature is enabled, every 249 When the NFS export feature is enabled, every copied up directory is
250 indexed by the file handle of the lower inode 250 indexed by the file handle of the lower inode and a file handle of the
251 upper directory is stored in a "trusted.overla 251 upper directory is stored in a "trusted.overlay.upper" extended attribute
252 on the index entry. On lookup of a merged dir 252 on the index entry. On lookup of a merged directory, if the upper
253 directory does not match the file handle store 253 directory does not match the file handle stores in the index, that is an
254 indication that multiple upper directories may 254 indication that multiple upper directories may be redirected to the same
255 lower directory. In that case, lookup returns 255 lower directory. In that case, lookup returns an error and warns about
256 a possible inconsistency. 256 a possible inconsistency.
257 257
258 Because lower layer redirects cannot be verifi 258 Because lower layer redirects cannot be verified with the index, enabling
259 NFS export support on an overlay filesystem wi 259 NFS export support on an overlay filesystem with no upper layer requires
260 turning off redirect follow (e.g. "redirect_di 260 turning off redirect follow (e.g. "redirect_dir=nofollow").
261 261
262 262
263 Non-directories 263 Non-directories
264 --------------- 264 ---------------
265 265
266 Objects that are not directories (files, symli 266 Objects that are not directories (files, symlinks, device-special
267 files etc.) are presented either from the uppe 267 files etc.) are presented either from the upper or lower filesystem as
268 appropriate. When a file in the lower filesys 268 appropriate. When a file in the lower filesystem is accessed in a way
269 the requires write-access, such as opening for 269 the requires write-access, such as opening for write access, changing
270 some metadata etc., the file is first copied f 270 some metadata etc., the file is first copied from the lower filesystem
271 to the upper filesystem (copy_up). Note that 271 to the upper filesystem (copy_up). Note that creating a hard-link
272 also requires copy_up, though of course creati 272 also requires copy_up, though of course creation of a symlink does
273 not. 273 not.
274 274
275 The copy_up may turn out to be unnecessary, fo 275 The copy_up may turn out to be unnecessary, for example if the file is
276 opened for read-write but the data is not modi 276 opened for read-write but the data is not modified.
277 277
278 The copy_up process first makes sure that the 278 The copy_up process first makes sure that the containing directory
279 exists in the upper filesystem - creating it a 279 exists in the upper filesystem - creating it and any parents as
280 necessary. It then creates the object with th 280 necessary. It then creates the object with the same metadata (owner,
281 mode, mtime, symlink-target etc.) and then if 281 mode, mtime, symlink-target etc.) and then if the object is a file, the
282 data is copied from the lower to the upper fil 282 data is copied from the lower to the upper filesystem. Finally any
283 extended attributes are copied up. 283 extended attributes are copied up.
284 284
285 Once the copy_up is complete, the overlay file 285 Once the copy_up is complete, the overlay filesystem simply
286 provides direct access to the newly created fi 286 provides direct access to the newly created file in the upper
287 filesystem - future operations on the file are 287 filesystem - future operations on the file are barely noticed by the
288 overlay filesystem (though an operation on the 288 overlay filesystem (though an operation on the name of the file such as
289 rename or unlink will of course be noticed and 289 rename or unlink will of course be noticed and handled).
290 290
291 291
292 Permission model 292 Permission model
293 ---------------- 293 ----------------
294 294
295 Permission checking in the overlay filesystem 295 Permission checking in the overlay filesystem follows these principles:
296 296
297 1) permission check SHOULD return the same re 297 1) permission check SHOULD return the same result before and after copy up
298 298
299 2) task creating the overlay mount MUST NOT g 299 2) task creating the overlay mount MUST NOT gain additional privileges
300 300
301 3) non-mounting task MAY gain additional priv 301 3) non-mounting task MAY gain additional privileges through the overlay,
302 compared to direct access on underlying lo 302 compared to direct access on underlying lower or upper filesystems
303 303
304 This is achieved by performing two permission 304 This is achieved by performing two permission checks on each access:
305 305
306 a) check if current task is allowed access ba 306 a) check if current task is allowed access based on local DAC (owner,
307 group, mode and posix acl), as well as MAC 307 group, mode and posix acl), as well as MAC checks
308 308
309 b) check if mounting task would be allowed re 309 b) check if mounting task would be allowed real operation on lower or
310 upper layer based on underlying filesystem 310 upper layer based on underlying filesystem permissions, again including
311 MAC checks 311 MAC checks
312 312
313 Check (a) ensures consistency (1) since owner, 313 Check (a) ensures consistency (1) since owner, group, mode and posix acls
314 are copied up. On the other hand it can resul 314 are copied up. On the other hand it can result in server enforced
315 permissions (used by NFS, for example) being i 315 permissions (used by NFS, for example) being ignored (3).
316 316
317 Check (b) ensures that no task gains permissio 317 Check (b) ensures that no task gains permissions to underlying layers that
318 the mounting task does not have (2). This als 318 the mounting task does not have (2). This also means that it is possible
319 to create setups where the consistency rule (1 319 to create setups where the consistency rule (1) does not hold; normally,
320 however, the mounting task will have sufficien 320 however, the mounting task will have sufficient privileges to perform all
321 operations. 321 operations.
322 322
323 Another way to demonstrate this model is drawi 323 Another way to demonstrate this model is drawing parallels between::
324 324
325 mount -t overlay overlay -olowerdir=/lower,u 325 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged
326 326
327 and:: 327 and::
328 328
329 cp -a /lower /upper 329 cp -a /lower /upper
330 mount --bind /upper /merged 330 mount --bind /upper /merged
331 331
332 The resulting access permissions should be the 332 The resulting access permissions should be the same. The difference is in
333 the time of copy (on-demand vs. up-front). 333 the time of copy (on-demand vs. up-front).
334 334
335 335
336 Multiple lower layers 336 Multiple lower layers
337 --------------------- 337 ---------------------
338 338
339 Multiple lower layers can now be given using t 339 Multiple lower layers can now be given using the colon (":") as a
340 separator character between the directory name 340 separator character between the directory names. For example::
341 341
342 mount -t overlay overlay -olowerdir=/lower1: 342 mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
343 343
344 As the example shows, "upperdir=" and "workdir 344 As the example shows, "upperdir=" and "workdir=" may be omitted. In
345 that case the overlay will be read-only. 345 that case the overlay will be read-only.
346 346
347 The specified lower directories will be stacke 347 The specified lower directories will be stacked beginning from the
348 rightmost one and going left. In the above ex 348 rightmost one and going left. In the above example lower1 will be the
349 top, lower2 the middle and lower3 the bottom l 349 top, lower2 the middle and lower3 the bottom layer.
350 350
351 Note: directory names containing colons can be 351 Note: directory names containing colons can be provided as lower layer by
352 escaping the colons with a single backslash. 352 escaping the colons with a single backslash. For example::
353 353
354 mount -t overlay overlay -olowerdir=/a\:lowe 354 mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged
355 355
356 Since kernel version v6.8, directory names con 356 Since kernel version v6.8, directory names containing colons can also
357 be configured as lower layer using the "lowerd 357 be configured as lower layer using the "lowerdir+" mount options and the
358 fsconfig syscall from new mount api. For exam 358 fsconfig syscall from new mount api. For example::
359 359
360 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerd 360 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/a:lower::dir", 0);
361 361
362 In the latter case, colons in lower layer dire 362 In the latter case, colons in lower layer directory names will be escaped
363 as an octal characters (\072) when displayed i 363 as an octal characters (\072) when displayed in /proc/self/mountinfo.
364 364
365 Metadata only copy up 365 Metadata only copy up
366 --------------------- 366 ---------------------
367 367
368 When the "metacopy" feature is enabled, overla 368 When the "metacopy" feature is enabled, overlayfs will only copy
369 up metadata (as opposed to whole file), when a 369 up metadata (as opposed to whole file), when a metadata specific operation
370 like chown/chmod is performed. Full file will 370 like chown/chmod is performed. Full file will be copied up later when
371 file is opened for WRITE operation. 371 file is opened for WRITE operation.
372 372
373 In other words, this is delayed data copy up o 373 In other words, this is delayed data copy up operation and data is copied
374 up when there is a need to actually modify dat 374 up when there is a need to actually modify data.
375 375
376 There are multiple ways to enable/disable this 376 There are multiple ways to enable/disable this feature. A config option
377 CONFIG_OVERLAY_FS_METACOPY can be set/unset to 377 CONFIG_OVERLAY_FS_METACOPY can be set/unset to enable/disable this feature
378 by default. Or one can enable/disable it at mo 378 by default. Or one can enable/disable it at module load time with module
379 parameter metacopy=on/off. Lastly, there is al 379 parameter metacopy=on/off. Lastly, there is also a per mount option
380 metacopy=on/off to enable/disable this feature 380 metacopy=on/off to enable/disable this feature per mount.
381 381
382 Do not use metacopy=on with untrusted upper/lo 382 Do not use metacopy=on with untrusted upper/lower directories. Otherwise
383 it is possible that an attacker can create a h 383 it is possible that an attacker can create a handcrafted file with
384 appropriate REDIRECT and METACOPY xattrs, and 384 appropriate REDIRECT and METACOPY xattrs, and gain access to file on lower
385 pointed by REDIRECT. This should not be possib 385 pointed by REDIRECT. This should not be possible on local system as setting
386 "trusted." xattrs will require CAP_SYS_ADMIN. 386 "trusted." xattrs will require CAP_SYS_ADMIN. But it should be possible
387 for untrusted layers like from a pen drive. 387 for untrusted layers like from a pen drive.
388 388
389 Note: redirect_dir={off|nofollow|follow[*]} an 389 Note: redirect_dir={off|nofollow|follow[*]} and nfs_export=on mount options
390 conflict with metacopy=on, and will result in 390 conflict with metacopy=on, and will result in an error.
391 391
392 [*] redirect_dir=follow only conflicts with me 392 [*] redirect_dir=follow only conflicts with metacopy=on if upperdir=... is
393 given. 393 given.
394 394
395 395
396 Data-only lower layers 396 Data-only lower layers
397 ---------------------- 397 ----------------------
398 398
399 With "metacopy" feature enabled, an overlayfs 399 With "metacopy" feature enabled, an overlayfs regular file may be a composition
400 of information from up to three different laye 400 of information from up to three different layers:
401 401
402 1) metadata from a file in the upper layer 402 1) metadata from a file in the upper layer
403 403
404 2) st_ino and st_dev object identifier from a 404 2) st_ino and st_dev object identifier from a file in a lower layer
405 405
406 3) data from a file in another lower layer (f 406 3) data from a file in another lower layer (further below)
407 407
408 The "lower data" file can be on any lower laye 408 The "lower data" file can be on any lower layer, except from the top most
409 lower layer. 409 lower layer.
410 410
411 Below the top most lower layer, any number of 411 Below the top most lower layer, any number of lower most layers may be defined
412 as "data-only" lower layers, using double colo 412 as "data-only" lower layers, using double colon ("::") separators.
413 A normal lower layer is not allowed to be belo 413 A normal lower layer is not allowed to be below a data-only layer, so single
414 colon separators are not allowed to the right 414 colon separators are not allowed to the right of double colon ("::") separators.
415 415
416 416
417 For example:: 417 For example::
418 418
419 mount -t overlay overlay -olowerdir=/l1:/l2: 419 mount -t overlay overlay -olowerdir=/l1:/l2:/l3::/do1::/do2 /merged
420 420
421 The paths of files in the "data-only" lower la 421 The paths of files in the "data-only" lower layers are not visible in the
422 merged overlayfs directories and the metadata 422 merged overlayfs directories and the metadata and st_ino/st_dev of files
423 in the "data-only" lower layers are not visibl 423 in the "data-only" lower layers are not visible in overlayfs inodes.
424 424
425 Only the data of the files in the "data-only" 425 Only the data of the files in the "data-only" lower layers may be visible
426 when a "metacopy" file in one of the lower lay 426 when a "metacopy" file in one of the lower layers above it, has a "redirect"
427 to the absolute path of the "lower data" file 427 to the absolute path of the "lower data" file in the "data-only" lower layer.
428 428
429 Since kernel version v6.8, "data-only" lower l 429 Since kernel version v6.8, "data-only" lower layers can also be added using
430 the "datadir+" mount options and the fsconfig 430 the "datadir+" mount options and the fsconfig syscall from new mount api.
431 For example:: 431 For example::
432 432
433 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerd 433 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l1", 0);
434 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerd 434 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l2", 0);
435 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerd 435 fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l3", 0);
436 fsconfig(fs_fd, FSCONFIG_SET_STRING, "datadi 436 fsconfig(fs_fd, FSCONFIG_SET_STRING, "datadir+", "/do1", 0);
437 fsconfig(fs_fd, FSCONFIG_SET_STRING, "datadi 437 fsconfig(fs_fd, FSCONFIG_SET_STRING, "datadir+", "/do2", 0);
438 438
439 439
440 fs-verity support 440 fs-verity support
441 ----------------- 441 -----------------
442 442
443 During metadata copy up of a lower file, if th 443 During metadata copy up of a lower file, if the source file has
444 fs-verity enabled and overlay verity support i 444 fs-verity enabled and overlay verity support is enabled, then the
445 digest of the lower file is added to the "trus 445 digest of the lower file is added to the "trusted.overlay.metacopy"
446 xattr. This is then used to verify the content 446 xattr. This is then used to verify the content of the lower file
447 each the time the metacopy file is opened. 447 each the time the metacopy file is opened.
448 448
449 When a layer containing verity xattrs is used, 449 When a layer containing verity xattrs is used, it means that any such
450 metacopy file in the upper layer is guaranteed 450 metacopy file in the upper layer is guaranteed to match the content
451 that was in the lower at the time of the copy- 451 that was in the lower at the time of the copy-up. If at any time
452 (during a mount, after a remount, etc) such a 452 (during a mount, after a remount, etc) such a file in the lower is
453 replaced or modified in any way, access to the 453 replaced or modified in any way, access to the corresponding file in
454 overlayfs will result in EIO errors (either on 454 overlayfs will result in EIO errors (either on open, due to overlayfs
455 digest check, or from a later read due to fs-v 455 digest check, or from a later read due to fs-verity) and a detailed
456 error is printed to the kernel logs. For more 456 error is printed to the kernel logs. For more details of how fs-verity
457 file access works, see :ref:`Documentation/fil 457 file access works, see :ref:`Documentation/filesystems/fsverity.rst
458 <accessing_verity_files>`. 458 <accessing_verity_files>`.
459 459
460 Verity can be used as a general robustness che 460 Verity can be used as a general robustness check to detect accidental
461 changes in the overlayfs directories in use. B 461 changes in the overlayfs directories in use. But, with additional care
462 it can also give more powerful guarantees. For 462 it can also give more powerful guarantees. For example, if the upper
463 layer is fully trusted (by using dm-verity or 463 layer is fully trusted (by using dm-verity or something similar), then
464 an untrusted lower layer can be used to supply 464 an untrusted lower layer can be used to supply validated file content
465 for all metacopy files. If additionally the u 465 for all metacopy files. If additionally the untrusted lower
466 directories are specified as "Data-only", then 466 directories are specified as "Data-only", then they can only supply
467 such file content, and the entire mount can be 467 such file content, and the entire mount can be trusted to match the
468 upper layer. 468 upper layer.
469 469
470 This feature is controlled by the "verity" mou 470 This feature is controlled by the "verity" mount option, which
471 supports these values: 471 supports these values:
472 472
473 - "off": 473 - "off":
474 The metacopy digest is never generated or 474 The metacopy digest is never generated or used. This is the
475 default if verity option is not specified. 475 default if verity option is not specified.
476 - "on": 476 - "on":
477 Whenever a metacopy files specifies an exp 477 Whenever a metacopy files specifies an expected digest, the
478 corresponding data file must match the spe 478 corresponding data file must match the specified digest. When
479 generating a metacopy file the verity dige 479 generating a metacopy file the verity digest will be set in it
480 based on the source file (if it has one). 480 based on the source file (if it has one).
481 - "require": 481 - "require":
482 Same as "on", but additionally all metacop 482 Same as "on", but additionally all metacopy files must specify a
483 digest (or EIO is returned on open). This 483 digest (or EIO is returned on open). This means metadata copy up
484 will only be used if the data file has fs- 484 will only be used if the data file has fs-verity enabled,
485 otherwise a full copy-up is used. 485 otherwise a full copy-up is used.
486 486
487 Sharing and copying layers 487 Sharing and copying layers
488 -------------------------- 488 --------------------------
489 489
490 Lower layers may be shared among several overl 490 Lower layers may be shared among several overlay mounts and that is indeed
491 a very common practice. An overlay mount may 491 a very common practice. An overlay mount may use the same lower layer
492 path as another overlay mount and it may use a 492 path as another overlay mount and it may use a lower layer path that is
493 beneath or above the path of another overlay l 493 beneath or above the path of another overlay lower layer path.
494 494
495 Using an upper layer path and/or a workdir pat 495 Using an upper layer path and/or a workdir path that are already used by
496 another overlay mount is not allowed and may f 496 another overlay mount is not allowed and may fail with EBUSY. Using
497 partially overlapping paths is not allowed and 497 partially overlapping paths is not allowed and may fail with EBUSY.
498 If files are accessed from two overlayfs mount 498 If files are accessed from two overlayfs mounts which share or overlap the
499 upper layer and/or workdir path the behavior o 499 upper layer and/or workdir path the behavior of the overlay is undefined,
500 though it will not result in a crash or deadlo 500 though it will not result in a crash or deadlock.
501 501
502 Mounting an overlay using an upper layer path, 502 Mounting an overlay using an upper layer path, where the upper layer path
503 was previously used by another mounted overlay 503 was previously used by another mounted overlay in combination with a
504 different lower layer path, is allowed, unless 504 different lower layer path, is allowed, unless the "index" or "metacopy"
505 features are enabled. 505 features are enabled.
506 506
507 With the "index" feature, on the first time mo 507 With the "index" feature, on the first time mount, an NFS file
508 handle of the lower layer root directory, alon 508 handle of the lower layer root directory, along with the UUID of the lower
509 filesystem, are encoded and stored in the "tru 509 filesystem, are encoded and stored in the "trusted.overlay.origin" extended
510 attribute on the upper layer root directory. 510 attribute on the upper layer root directory. On subsequent mount attempts,
511 the lower root directory file handle and lower 511 the lower root directory file handle and lower filesystem UUID are compared
512 to the stored origin in upper root directory. 512 to the stored origin in upper root directory. On failure to verify the
513 lower root origin, mount will fail with ESTALE 513 lower root origin, mount will fail with ESTALE. An overlayfs mount with
514 "index" enabled will fail with EOPNOTSUPP if t 514 "index" enabled will fail with EOPNOTSUPP if the lower filesystem
515 does not support NFS export, lower filesystem 515 does not support NFS export, lower filesystem does not have a valid UUID or
516 if the upper filesystem does not support exten 516 if the upper filesystem does not support extended attributes.
517 517
518 For the "metacopy" feature, there is no verifi 518 For the "metacopy" feature, there is no verification mechanism at
519 mount time. So if same upper is mounted with d 519 mount time. So if same upper is mounted with different set of lower, mount
520 probably will succeed but expect the unexpecte 520 probably will succeed but expect the unexpected later on. So don't do it.
521 521
522 It is quite a common practice to copy overlay 522 It is quite a common practice to copy overlay layers to a different
523 directory tree on the same or different underl 523 directory tree on the same or different underlying filesystem, and even
524 to a different machine. With the "index" feat 524 to a different machine. With the "index" feature, trying to mount
525 the copied layers will fail the verification o 525 the copied layers will fail the verification of the lower root file handle.
526 526
527 Nesting overlayfs mounts 527 Nesting overlayfs mounts
528 ------------------------ 528 ------------------------
529 529
530 It is possible to use a lower directory that i 530 It is possible to use a lower directory that is stored on an overlayfs
531 mount. For regular files this does not need an 531 mount. For regular files this does not need any special care. However, files
532 that have overlayfs attributes, such as whiteo 532 that have overlayfs attributes, such as whiteouts or "overlay.*" xattrs will be
533 interpreted by the underlying overlayfs mount 533 interpreted by the underlying overlayfs mount and stripped out. In order to
534 allow the second overlayfs mount to see the at 534 allow the second overlayfs mount to see the attributes they must be escaped.
535 535
536 Overlayfs specific xattrs are escaped by using 536 Overlayfs specific xattrs are escaped by using a special prefix of
537 "overlay.overlay.". So, a file with a "trusted 537 "overlay.overlay.". So, a file with a "trusted.overlay.overlay.metacopy" xattr
538 in the lower dir will be exposed as a regular 538 in the lower dir will be exposed as a regular file with a
539 "trusted.overlay.metacopy" xattr in the overla 539 "trusted.overlay.metacopy" xattr in the overlayfs mount. This can be nested by
540 repeating the prefix multiple time, as each in 540 repeating the prefix multiple time, as each instance only removes one prefix.
541 541
542 A lower dir with a regular whiteout will alway 542 A lower dir with a regular whiteout will always be handled by the overlayfs
543 mount, so to support storing an effective whit 543 mount, so to support storing an effective whiteout file in an overlayfs mount an
544 alternative form of whiteout is supported. Thi 544 alternative form of whiteout is supported. This form is a regular, zero-size
545 file with the "overlay.whiteout" xattr set, in 545 file with the "overlay.whiteout" xattr set, inside a directory with the
546 "overlay.opaque" xattr set to "x" (see `whiteo 546 "overlay.opaque" xattr set to "x" (see `whiteouts and opaque directories`_).
547 These alternative whiteouts are never created 547 These alternative whiteouts are never created by overlayfs, but can be used by
548 userspace tools (like containers) that generat 548 userspace tools (like containers) that generate lower layers.
549 These alternative whiteouts can be escaped usi 549 These alternative whiteouts can be escaped using the standard xattr escape
550 mechanism in order to properly nest to any dep 550 mechanism in order to properly nest to any depth.
551 551
552 Non-standard behavior 552 Non-standard behavior
553 --------------------- 553 ---------------------
554 554
555 Current version of overlayfs can act as a most 555 Current version of overlayfs can act as a mostly POSIX compliant
556 filesystem. 556 filesystem.
557 557
558 This is the list of cases that overlayfs doesn 558 This is the list of cases that overlayfs doesn't currently handle:
559 559
560 a) POSIX mandates updating st_atime for reads 560 a) POSIX mandates updating st_atime for reads. This is currently not
561 done in the case when the file resides on 561 done in the case when the file resides on a lower layer.
562 562
563 b) If a file residing on a lower layer is ope 563 b) If a file residing on a lower layer is opened for read-only and then
564 memory mapped with MAP_SHARED, then subseq 564 memory mapped with MAP_SHARED, then subsequent changes to the file are not
565 reflected in the memory mapping. 565 reflected in the memory mapping.
566 566
567 c) If a file residing on a lower layer is bei 567 c) If a file residing on a lower layer is being executed, then opening that
568 file for write or truncating the file will 568 file for write or truncating the file will not be denied with ETXTBSY.
569 569
570 The following options allow overlayfs to act m 570 The following options allow overlayfs to act more like a standards
571 compliant filesystem: 571 compliant filesystem:
572 572
573 redirect_dir 573 redirect_dir
574 ```````````` 574 ````````````
575 575
576 Enabled with the mount option or module option 576 Enabled with the mount option or module option: "redirect_dir=on" or with
577 the kernel config option CONFIG_OVERLAY_FS_RED 577 the kernel config option CONFIG_OVERLAY_FS_REDIRECT_DIR=y.
578 578
579 If this feature is disabled, then rename(2) on 579 If this feature is disabled, then rename(2) on a lower or merged directory
580 will fail with EXDEV ("Invalid cross-device li 580 will fail with EXDEV ("Invalid cross-device link").
581 581
582 index 582 index
583 ````` 583 `````
584 584
585 Enabled with the mount option or module option 585 Enabled with the mount option or module option "index=on" or with the
586 kernel config option CONFIG_OVERLAY_FS_INDEX=y 586 kernel config option CONFIG_OVERLAY_FS_INDEX=y.
587 587
588 If this feature is disabled and a file with mu 588 If this feature is disabled and a file with multiple hard links is copied
589 up, then this will "break" the link. Changes 589 up, then this will "break" the link. Changes will not be propagated to
590 other names referring to the same inode. 590 other names referring to the same inode.
591 591
592 xino 592 xino
593 ```` 593 ````
594 594
595 Enabled with the mount option "xino=auto" or " 595 Enabled with the mount option "xino=auto" or "xino=on", with the module
596 option "xino_auto=on" or with the kernel confi 596 option "xino_auto=on" or with the kernel config option
597 CONFIG_OVERLAY_FS_XINO_AUTO=y. Also implicitl 597 CONFIG_OVERLAY_FS_XINO_AUTO=y. Also implicitly enabled by using the same
598 underlying filesystem for all layers making up 598 underlying filesystem for all layers making up the overlay.
599 599
600 If this feature is disabled or the underlying 600 If this feature is disabled or the underlying filesystem doesn't have
601 enough free bits in the inode number, then ove 601 enough free bits in the inode number, then overlayfs will not be able to
602 guarantee that the values of st_ino and st_dev 602 guarantee that the values of st_ino and st_dev returned by stat(2) and the
603 value of d_ino returned by readdir(3) will act 603 value of d_ino returned by readdir(3) will act like on a normal filesystem.
604 E.g. the value of st_dev may be different for 604 E.g. the value of st_dev may be different for two objects in the same
605 overlay filesystem and the value of st_ino for 605 overlay filesystem and the value of st_ino for filesystem objects may not be
606 persistent and could change even while the ove 606 persistent and could change even while the overlay filesystem is mounted, as
607 summarized in the `Inode properties`_ table ab 607 summarized in the `Inode properties`_ table above.
608 608
609 609
610 Changes to underlying filesystems 610 Changes to underlying filesystems
611 --------------------------------- 611 ---------------------------------
612 612
613 Changes to the underlying filesystems while pa 613 Changes to the underlying filesystems while part of a mounted overlay
614 filesystem are not allowed. If the underlying 614 filesystem are not allowed. If the underlying filesystem is changed,
615 the behavior of the overlay is undefined, thou 615 the behavior of the overlay is undefined, though it will not result in
616 a crash or deadlock. 616 a crash or deadlock.
617 617
618 Offline changes, when the overlay is not mount 618 Offline changes, when the overlay is not mounted, are allowed to the
619 upper tree. Offline changes to the lower tree 619 upper tree. Offline changes to the lower tree are only allowed if the
620 "metacopy", "index", "xino" and "redirect_dir" 620 "metacopy", "index", "xino" and "redirect_dir" features
621 have not been used. If the lower tree is modi 621 have not been used. If the lower tree is modified and any of these
622 features has been used, the behavior of the ov 622 features has been used, the behavior of the overlay is undefined,
623 though it will not result in a crash or deadlo 623 though it will not result in a crash or deadlock.
624 624
625 When the overlay NFS export feature is enabled 625 When the overlay NFS export feature is enabled, overlay filesystems
626 behavior on offline changes of the underlying 626 behavior on offline changes of the underlying lower layer is different
627 than the behavior when NFS export is disabled. 627 than the behavior when NFS export is disabled.
628 628
629 On every copy_up, an NFS file handle of the lo 629 On every copy_up, an NFS file handle of the lower inode, along with the
630 UUID of the lower filesystem, are encoded and 630 UUID of the lower filesystem, are encoded and stored in an extended
631 attribute "trusted.overlay.origin" on the uppe 631 attribute "trusted.overlay.origin" on the upper inode.
632 632
633 When the NFS export feature is enabled, a look 633 When the NFS export feature is enabled, a lookup of a merged directory,
634 that found a lower directory at the lookup pat 634 that found a lower directory at the lookup path or at the path pointed
635 to by the "trusted.overlay.redirect" extended 635 to by the "trusted.overlay.redirect" extended attribute, will verify
636 that the found lower directory file handle and 636 that the found lower directory file handle and lower filesystem UUID
637 match the origin file handle that was stored a 637 match the origin file handle that was stored at copy_up time. If a
638 found lower directory does not match the store 638 found lower directory does not match the stored origin, that directory
639 will not be merged with the upper directory. 639 will not be merged with the upper directory.
640 640
641 641
642 642
643 NFS export 643 NFS export
644 ---------- 644 ----------
645 645
646 When the underlying filesystems supports NFS e 646 When the underlying filesystems supports NFS export and the "nfs_export"
647 feature is enabled, an overlay filesystem may 647 feature is enabled, an overlay filesystem may be exported to NFS.
648 648
649 With the "nfs_export" feature, on copy_up of a 649 With the "nfs_export" feature, on copy_up of any lower object, an index
650 entry is created under the index directory. T 650 entry is created under the index directory. The index entry name is the
651 hexadecimal representation of the copy up orig 651 hexadecimal representation of the copy up origin file handle. For a
652 non-directory object, the index entry is a har 652 non-directory object, the index entry is a hard link to the upper inode.
653 For a directory object, the index entry has an 653 For a directory object, the index entry has an extended attribute
654 "trusted.overlay.upper" with an encoded file h 654 "trusted.overlay.upper" with an encoded file handle of the upper
655 directory inode. 655 directory inode.
656 656
657 When encoding a file handle from an overlay fi 657 When encoding a file handle from an overlay filesystem object, the
658 following rules apply: 658 following rules apply:
659 659
660 1. For a non-upper object, encode a lower fil 660 1. For a non-upper object, encode a lower file handle from lower inode
661 2. For an indexed object, encode a lower file 661 2. For an indexed object, encode a lower file handle from copy_up origin
662 3. For a pure-upper object and for an existin 662 3. For a pure-upper object and for an existing non-indexed upper object,
663 encode an upper file handle from upper ino 663 encode an upper file handle from upper inode
664 664
665 The encoded overlay file handle includes: 665 The encoded overlay file handle includes:
666 666
667 - Header including path type information (e.g 667 - Header including path type information (e.g. lower/upper)
668 - UUID of the underlying filesystem 668 - UUID of the underlying filesystem
669 - Underlying filesystem encoding of underlyin 669 - Underlying filesystem encoding of underlying inode
670 670
671 This encoding format is identical to the encod 671 This encoding format is identical to the encoding format file handles that
672 are stored in extended attribute "trusted.over 672 are stored in extended attribute "trusted.overlay.origin".
673 673
674 When decoding an overlay file handle, the foll 674 When decoding an overlay file handle, the following steps are followed:
675 675
676 1. Find underlying layer by UUID and path typ 676 1. Find underlying layer by UUID and path type information.
677 2. Decode the underlying filesystem file hand 677 2. Decode the underlying filesystem file handle to underlying dentry.
678 3. For a lower file handle, lookup the handle 678 3. For a lower file handle, lookup the handle in index directory by name.
679 4. If a whiteout is found in index, return ES 679 4. If a whiteout is found in index, return ESTALE. This represents an
680 overlay object that was deleted after its 680 overlay object that was deleted after its file handle was encoded.
681 5. For a non-directory, instantiate a disconn 681 5. For a non-directory, instantiate a disconnected overlay dentry from the
682 decoded underlying dentry, the path type a 682 decoded underlying dentry, the path type and index inode, if found.
683 6. For a directory, use the connected underly 683 6. For a directory, use the connected underlying decoded dentry, path type
684 and index, to lookup a connected overlay d 684 and index, to lookup a connected overlay dentry.
685 685
686 Decoding a non-directory file handle may retur 686 Decoding a non-directory file handle may return a disconnected dentry.
687 copy_up of that disconnected dentry will creat 687 copy_up of that disconnected dentry will create an upper index entry with
688 no upper alias. 688 no upper alias.
689 689
690 When overlay filesystem has multiple lower lay 690 When overlay filesystem has multiple lower layers, a middle layer
691 directory may have a "redirect" to lower direc 691 directory may have a "redirect" to lower directory. Because middle layer
692 "redirects" are not indexed, a lower file hand 692 "redirects" are not indexed, a lower file handle that was encoded from the
693 "redirect" origin directory, cannot be used to 693 "redirect" origin directory, cannot be used to find the middle or upper
694 layer directory. Similarly, a lower file hand 694 layer directory. Similarly, a lower file handle that was encoded from a
695 descendant of the "redirect" origin directory, 695 descendant of the "redirect" origin directory, cannot be used to
696 reconstruct a connected overlay path. To miti 696 reconstruct a connected overlay path. To mitigate the cases of
697 directories that cannot be decoded from a lowe 697 directories that cannot be decoded from a lower file handle, these
698 directories are copied up on encode and encode 698 directories are copied up on encode and encoded as an upper file handle.
699 On an overlay filesystem with no upper layer t 699 On an overlay filesystem with no upper layer this mitigation cannot be
700 used NFS export in this setup requires turning 700 used NFS export in this setup requires turning off redirect follow (e.g.
701 "redirect_dir=nofollow"). 701 "redirect_dir=nofollow").
702 702
703 The overlay filesystem does not support non-di 703 The overlay filesystem does not support non-directory connectable file
704 handles, so exporting with the 'subtree_check' 704 handles, so exporting with the 'subtree_check' exportfs configuration will
705 cause failures to lookup files over NFS. 705 cause failures to lookup files over NFS.
706 706
707 When the NFS export feature is enabled, all di 707 When the NFS export feature is enabled, all directory index entries are
708 verified on mount time to check that upper fil 708 verified on mount time to check that upper file handles are not stale.
709 This verification may cause significant overhe 709 This verification may cause significant overhead in some cases.
710 710
711 Note: the mount options index=off,nfs_export=o 711 Note: the mount options index=off,nfs_export=on are conflicting for a
712 read-write mount and will result in an error. 712 read-write mount and will result in an error.
713 713
714 Note: the mount option uuid=off can be used to 714 Note: the mount option uuid=off can be used to replace UUID of the underlying
715 filesystem in file handles with null, and effe 715 filesystem in file handles with null, and effectively disable UUID checks. This
716 can be useful in case the underlying disk is c 716 can be useful in case the underlying disk is copied and the UUID of this copy
717 is changed. This is only applicable if all low 717 is changed. This is only applicable if all lower/upper/work directories are on
718 the same filesystem, otherwise it will fallbac 718 the same filesystem, otherwise it will fallback to normal behaviour.
719 719
720 720
721 UUID and fsid 721 UUID and fsid
722 ------------- 722 -------------
723 723
724 The UUID of overlayfs instance itself and the 724 The UUID of overlayfs instance itself and the fsid reported by statfs(2) are
725 controlled by the "uuid" mount option, which s 725 controlled by the "uuid" mount option, which supports these values:
726 726
727 - "null": 727 - "null":
728 UUID of overlayfs is null. fsid is taken f 728 UUID of overlayfs is null. fsid is taken from upper most filesystem.
729 - "off": 729 - "off":
730 UUID of overlayfs is null. fsid is taken f 730 UUID of overlayfs is null. fsid is taken from upper most filesystem.
731 UUID of underlying layers is ignored. 731 UUID of underlying layers is ignored.
732 - "on": 732 - "on":
733 UUID of overlayfs is generated and used to 733 UUID of overlayfs is generated and used to report a unique fsid.
734 UUID is stored in xattr "trusted.overlay.u 734 UUID is stored in xattr "trusted.overlay.uuid", making overlayfs fsid
735 unique and persistent. This option requir 735 unique and persistent. This option requires an overlayfs with upper
736 filesystem that supports xattrs. 736 filesystem that supports xattrs.
737 - "auto": (default) 737 - "auto": (default)
738 UUID is taken from xattr "trusted.overlay. 738 UUID is taken from xattr "trusted.overlay.uuid" if it exists.
739 Upgrade to "uuid=on" on first time mount o 739 Upgrade to "uuid=on" on first time mount of new overlay filesystem that
740 meets the prerequites. 740 meets the prerequites.
741 Downgrade to "uuid=null" for existing over 741 Downgrade to "uuid=null" for existing overlay filesystems that were never
742 mounted with "uuid=on". 742 mounted with "uuid=on".
743 743
744 744
745 Volatile mount 745 Volatile mount
746 -------------- 746 --------------
747 747
748 This is enabled with the "volatile" mount opti 748 This is enabled with the "volatile" mount option. Volatile mounts are not
749 guaranteed to survive a crash. It is strongly 749 guaranteed to survive a crash. It is strongly recommended that volatile
750 mounts are only used if data written to the ov 750 mounts are only used if data written to the overlay can be recreated
751 without significant effort. 751 without significant effort.
752 752
753 The advantage of mounting with the "volatile" 753 The advantage of mounting with the "volatile" option is that all forms of
754 sync calls to the upper filesystem are omitted 754 sync calls to the upper filesystem are omitted.
755 755
756 In order to avoid a giving a false sense of sa 756 In order to avoid a giving a false sense of safety, the syncfs (and fsync)
757 semantics of volatile mounts are slightly diff 757 semantics of volatile mounts are slightly different than that of the rest of
758 VFS. If any writeback error occurs on the upp 758 VFS. If any writeback error occurs on the upperdir's filesystem after a
759 volatile mount takes place, all sync functions 759 volatile mount takes place, all sync functions will return an error. Once this
760 condition is reached, the filesystem will not 760 condition is reached, the filesystem will not recover, and every subsequent sync
761 call will return an error, even if the upperdi 761 call will return an error, even if the upperdir has not experience a new error
762 since the last sync call. 762 since the last sync call.
763 763
764 When overlay is mounted with "volatile" option 764 When overlay is mounted with "volatile" option, the directory
765 "$workdir/work/incompat/volatile" is created. 765 "$workdir/work/incompat/volatile" is created. During next mount, overlay
766 checks for this directory and refuses to mount 766 checks for this directory and refuses to mount if present. This is a strong
767 indicator that user should throw away upper an 767 indicator that user should throw away upper and work directories and create
768 fresh one. In very limited cases where the use 768 fresh one. In very limited cases where the user knows that the system has
769 not crashed and contents of upperdir are intac 769 not crashed and contents of upperdir are intact, The "volatile" directory
770 can be removed. 770 can be removed.
771 771
772 772
773 User xattr 773 User xattr
774 ---------- 774 ----------
775 775
776 The "-o userxattr" mount option forces overlay 776 The "-o userxattr" mount option forces overlayfs to use the
777 "user.overlay." xattr namespace instead of "tr 777 "user.overlay." xattr namespace instead of "trusted.overlay.". This is
778 useful for unprivileged mounting of overlayfs. 778 useful for unprivileged mounting of overlayfs.
779 779
780 780
781 Testsuite 781 Testsuite
782 --------- 782 ---------
783 783
784 There's a testsuite originally developed by Da 784 There's a testsuite originally developed by David Howells and currently
785 maintained by Amir Goldstein at: 785 maintained by Amir Goldstein at:
786 786
787 https://github.com/amir73il/unionmount-testsui 787 https://github.com/amir73il/unionmount-testsuite.git
788 788
789 Run as root:: 789 Run as root::
790 790
791 # cd unionmount-testsuite 791 # cd unionmount-testsuite
792 # ./run --ov --verify 792 # ./run --ov --verify
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.