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