~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/filesystems/overlayfs.rst

Version: ~ [ linux-6.11.5 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.58 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.114 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.169 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.228 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.284 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.322 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.9 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/filesystems/overlayfs.rst (Version linux-6.11.5) and /Documentation/filesystems/overlayfs.rst (Version linux-5.0.21)


  1 .. SPDX-License-Identifier: GPL-2.0               
  2                                                   
  3 Written by: Neil Brown                            
  4 Please see MAINTAINERS file for where to send     
  5                                                   
  6 Overlay Filesystem                                
  7 ==================                                
  8                                                   
  9 This document describes a prototype for a new     
 10 overlay-filesystem functionality in Linux (som    
 11 union-filesystems).  An overlay-filesystem tri    
 12 filesystem which is the result over overlaying    
 13 of the other.                                     
 14                                                   
 15                                                   
 16 Overlay objects                                   
 17 ---------------                                   
 18                                                   
 19 The overlay filesystem approach is 'hybrid', b    
 20 appear in the filesystem do not always appear     
 21 In many cases, an object accessed in the union    
 22 from accessing the corresponding object from t    
 23 This is most obvious from the 'st_dev' field r    
 24                                                   
 25 While directories will report an st_dev from t    
 26 non-directory objects may report an st_dev fro    
 27 upper filesystem that is providing the object.    
 28 only be unique when combined with st_dev, and     
 29 over the lifetime of a non-directory object.      
 30 tools ignore these values and will not be affe    
 31                                                   
 32 In the special case of all overlay layers on t    
 33 filesystem, all objects will report an st_dev     
 34 filesystem and st_ino from the underlying file    
 35 make the overlay mount more compliant with fil    
 36 overlay objects will be distinguishable from t    
 37 objects in the original filesystem.               
 38                                                   
 39 On 64bit systems, even if all overlay layers a    
 40 underlying filesystem, the same compliant beha    
 41 with the "xino" feature.  The "xino" feature c    
 42 identifier from the real object st_ino and an     
 43 The "xino" feature uses the high inode number     
 44 underlying filesystems rarely use the high ino    
 45 the underlying inode number does overflow into    
 46 filesystem will fall back to the non xino beha    
 47                                                   
 48 The "xino" feature can be enabled with the "-o    
 49 If all underlying filesystems support NFS file    
 50 for overlay filesystem objects is not only uni    
 51 the lifetime of the filesystem.  The "-o xino=    
 52 enables the "xino" feature only if the persist    
 53                                                   
 54 The following table summarizes what can be exp    
 55 configurations.                                   
 56                                                   
 57 Inode properties                                  
 58 ````````````````                                  
 59                                                   
 60 +--------------+------------+------------+----    
 61 |Configuration | Persistent | Uniform    | st_    
 62 |              | st_ino     | st_dev     |        
 63 +==============+=====+======+=====+======+====    
 64 |              | dir | !dir | dir | !dir |  di    
 65 +--------------+-----+------+-----+------+----    
 66 | All layers   |  Y  |  Y   |  Y  |  Y   |  Y     
 67 | on same fs   |     |      |     |      |        
 68 +--------------+-----+------+-----+------+----    
 69 | Layers not   |  N  |  N   |  Y  |  N   |  N     
 70 | on same fs,  |     |      |     |      |        
 71 | xino=off     |     |      |     |      |        
 72 +--------------+-----+------+-----+------+----    
 73 | xino=on/auto |  Y  |  Y   |  Y  |  Y   |  Y     
 74 +--------------+-----+------+-----+------+----    
 75 | xino=on/auto,|  N  |  N   |  Y  |  N   |  N     
 76 | ino overflow |     |      |     |      |        
 77 +--------------+-----+------+-----+------+----    
 78                                                   
 79 [*] nfsd v3 readdirplus verifies d_ino == i_in    
 80 /proc files, such as /proc/locks and /proc/sel    
 81 file descriptor.                                  
 82                                                   
 83 Upper and Lower                                   
 84 ---------------                                   
 85                                                   
 86 An overlay filesystem combines two filesystems    
 87 and a 'lower' filesystem.  When a name exists     
 88 object in the 'upper' filesystem is visible wh    
 89 'lower' filesystem is either hidden or, in the    
 90 merged with the 'upper' object.                   
 91                                                   
 92 It would be more correct to refer to an upper     
 93 tree' rather than 'filesystem' as it is quite     
 94 directory trees to be in the same filesystem a    
 95 requirement that the root of a filesystem be g    
 96 lower.                                            
 97                                                   
 98 A wide range of filesystems supported by Linux    
 99 but not all filesystems that are mountable by     
100 needed for OverlayFS to work.  The lower files    
101 writable.  The lower filesystem can even be an    
102 filesystem will normally be writable and if it    
103 creation of trusted.* and/or user.* extended a    
104 valid d_type in readdir responses, so NFS is n    
105                                                   
106 A read-only overlay of two read-only filesyste    
107 filesystem type.                                  
108                                                   
109 Directories                                       
110 -----------                                       
111                                                   
112 Overlaying mainly involves directories.  If a     
113 upper and lower filesystems and refers to a no    
114 then the lower object is hidden - the name ref    
115 object.                                           
116                                                   
117 Where both upper and lower objects are directo    
118 is formed.                                        
119                                                   
120 At mount time, the two directories given as mo    
121 "upperdir" are combined into a merged director    
122                                                   
123   mount -t overlay overlay -olowerdir=/lower,u    
124   workdir=/work /merged                           
125                                                   
126 The "workdir" needs to be an empty directory o    
127 as upperdir.                                      
128                                                   
129 Then whenever a lookup is requested in such a     
130 lookup is performed in each actual directory a    
131 is cached in the dentry belonging to the overl    
132 actual lookups find directories, both are stor    
133 directory is created, otherwise only one is st    
134 exists, else the lower.                           
135                                                   
136 Only the lists of names from directories are m    
137 such as metadata and extended attributes are r    
138 directory only.  These attributes of the lower    
139                                                   
140 whiteouts and opaque directories                  
141 --------------------------------                  
142                                                   
143 In order to support rm and rmdir without chang    
144 filesystem, an overlay filesystem needs to rec    
145 that files have been removed.  This is done us    
146 directories (non-directories are always opaque    
147                                                   
148 A whiteout is created as a character device wi    
149 as a zero-size regular file with the xattr "tr    
150                                                   
151 When a whiteout is found in the upper level of    
152 matching name in the lower level is ignored, a    
153 is also hidden.                                   
154                                                   
155 A directory is made opaque by setting the xatt    
156 to "y".  Where the upper filesystem contains a    
157 directory in the lower filesystem with the sam    
158                                                   
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                                           
167 -------                                           
168                                                   
169 When a 'readdir' request is made on a merged d    
170 lower directories are each read and the name l    
171 obvious way (upper is read first, then lower -    
172 exist are not re-added).  This merged name lis    
173 'struct file' and so remains as long as the fi    
174 directory is opened and read by two processes     
175 will each have separate caches.  A seekdir to     
176 directory (offset 0) followed by a readdir wil    
177 discarded and rebuilt.                            
178                                                   
179 This means that changes to the merged director    
180 directory is being read.  This is unlikely to     
181 programs.                                         
182                                                   
183 seek offsets are assigned sequentially when th    
184 Thus if:                                          
185                                                   
186  - read part of a directory                       
187  - remember an offset, and close the directory    
188  - re-open the directory some time later          
189  - seek to the remembered offset                  
190                                                   
191 there may be little correlation between the ol    
192 the list of filenames, particularly if anythin    
193 directory.                                        
194                                                   
195 Readdir on directories that are not merged is     
196 underlying directory (upper or lower).            
197                                                   
198 renaming directories                              
199 --------------------                              
200                                                   
201 When renaming a directory that is on the lower    
202 directory was not created on the upper layer t    
203 handle it in two different ways:                  
204                                                   
205 1. return EXDEV error: this error is returned     
206    move a file or directory across filesystem     
207    applications are usually prepared to handle    
208    recursively copies the directory tree).  Th    
209                                                   
210 2. If the "redirect_dir" feature is enabled, t    
211    copied up (but not the contents).  Then the    
212    extended attribute is set to the path of th    
213    root of the overlay.  Finally the directory    
214    location.                                      
215                                                   
216 There are several ways to tune the "redirect_d    
217                                                   
218 Kernel config options:                            
219                                                   
220 - OVERLAY_FS_REDIRECT_DIR:                        
221     If this is enabled, then redirect_dir is t    
222 - OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:              
223     If this is enabled, then redirects are alw    
224     this results in a less secure configuratio    
225     worried about backward compatibility with     
226     feature and follow redirects even if turne    
227                                                   
228 Module options (can also be changed through /s    
229                                                   
230 - "redirect_dir=BOOL":                            
231     See OVERLAY_FS_REDIRECT_DIR kernel config     
232 - "redirect_always_follow=BOOL":                  
233     See OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW kern    
234 - "redirect_max=NUM":                             
235     The maximum number of bytes in an absolute    
236                                                   
237 Mount options:                                    
238                                                   
239 - "redirect_dir=on":                              
240     Redirects are enabled.                        
241 - "redirect_dir=follow":                          
242     Redirects are not created, but followed.      
243 - "redirect_dir=nofollow":                        
244     Redirects are not created and not followed    
245 - "redirect_dir=off":                             
246     If "redirect_always_follow" is enabled in     
247     this "off" translates to "follow", otherwi    
248                                                   
249 When the NFS export feature is enabled, every     
250 indexed by the file handle of the lower inode     
251 upper directory is stored in a "trusted.overla    
252 on the index entry.  On lookup of a merged dir    
253 directory does not match the file handle store    
254 indication that multiple upper directories may    
255 lower directory.  In that case, lookup returns    
256 a possible inconsistency.                         
257                                                   
258 Because lower layer redirects cannot be verifi    
259 NFS export support on an overlay filesystem wi    
260 turning off redirect follow (e.g. "redirect_di    
261                                                   
262                                                   
263 Non-directories                                   
264 ---------------                                   
265                                                   
266 Objects that are not directories (files, symli    
267 files etc.) are presented either from the uppe    
268 appropriate.  When a file in the lower filesys    
269 the requires write-access, such as opening for    
270 some metadata etc., the file is first copied f    
271 to the upper filesystem (copy_up).  Note that     
272 also requires copy_up, though of course creati    
273 not.                                              
274                                                   
275 The copy_up may turn out to be unnecessary, fo    
276 opened for read-write but the data is not modi    
277                                                   
278 The copy_up process first makes sure that the     
279 exists in the upper filesystem - creating it a    
280 necessary.  It then creates the object with th    
281 mode, mtime, symlink-target etc.) and then if     
282 data is copied from the lower to the upper fil    
283 extended attributes are copied up.                
284                                                   
285 Once the copy_up is complete, the overlay file    
286 provides direct access to the newly created fi    
287 filesystem - future operations on the file are    
288 overlay filesystem (though an operation on the    
289 rename or unlink will of course be noticed and    
290                                                   
291                                                   
292 Permission model                                  
293 ----------------                                  
294                                                   
295 Permission checking in the overlay filesystem     
296                                                   
297  1) permission check SHOULD return the same re    
298                                                   
299  2) task creating the overlay mount MUST NOT g    
300                                                   
301  3) non-mounting task MAY gain additional priv    
302     compared to direct access on underlying lo    
303                                                   
304 This is achieved by performing two permission     
305                                                   
306  a) check if current task is allowed access ba    
307     group, mode and posix acl), as well as MAC    
308                                                   
309  b) check if mounting task would be allowed re    
310     upper layer based on underlying filesystem    
311     MAC checks                                    
312                                                   
313 Check (a) ensures consistency (1) since owner,    
314 are copied up.  On the other hand it can resul    
315 permissions (used by NFS, for example) being i    
316                                                   
317 Check (b) ensures that no task gains permissio    
318 the mounting task does not have (2).  This als    
319 to create setups where the consistency rule (1    
320 however, the mounting task will have sufficien    
321 operations.                                       
322                                                   
323 Another way to demonstrate this model is drawi    
324                                                   
325   mount -t overlay overlay -olowerdir=/lower,u    
326                                                   
327 and::                                             
328                                                   
329   cp -a /lower /upper                             
330   mount --bind /upper /merged                     
331                                                   
332 The resulting access permissions should be the    
333 the time of copy (on-demand vs. up-front).        
334                                                   
335                                                   
336 Multiple lower layers                             
337 ---------------------                             
338                                                   
339 Multiple lower layers can now be given using t    
340 separator character between the directory name    
341                                                   
342   mount -t overlay overlay -olowerdir=/lower1:    
343                                                   
344 As the example shows, "upperdir=" and "workdir    
345 that case the overlay will be read-only.          
346                                                   
347 The specified lower directories will be stacke    
348 rightmost one and going left.  In the above ex    
349 top, lower2 the middle and lower3 the bottom l    
350                                                   
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                                                   
365 Metadata only copy up                             
366 ---------------------                             
367                                                   
368 When the "metacopy" feature is enabled, overla    
369 up metadata (as opposed to whole file), when a    
370 like chown/chmod is performed. Full file will     
371 file is opened for WRITE operation.               
372                                                   
373 In other words, this is delayed data copy up o    
374 up when there is a need to actually modify dat    
375                                                   
376 There are multiple ways to enable/disable this    
377 CONFIG_OVERLAY_FS_METACOPY can be set/unset to    
378 by default. Or one can enable/disable it at mo    
379 parameter metacopy=on/off. Lastly, there is al    
380 metacopy=on/off to enable/disable this feature    
381                                                   
382 Do not use metacopy=on with untrusted upper/lo    
383 it is possible that an attacker can create a h    
384 appropriate REDIRECT and METACOPY xattrs, and     
385 pointed by REDIRECT. This should not be possib    
386 "trusted." xattrs will require CAP_SYS_ADMIN.     
387 for untrusted layers like from a pen drive.       
388                                                   
389 Note: redirect_dir={off|nofollow|follow[*]} an    
390 conflict with metacopy=on, and will result in     
391                                                   
392 [*] redirect_dir=follow only conflicts with me    
393 given.                                            
394                                                   
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                        
488 --------------------------                        
489                                                   
490 Lower layers may be shared among several overl    
491 a very common practice.  An overlay mount may     
492 path as another overlay mount and it may use a    
493 beneath or above the path of another overlay l    
494                                                   
495 Using an upper layer path and/or a workdir pat    
496 another overlay mount is not allowed and may f    
497 partially overlapping paths is not allowed and    
498 If files are accessed from two overlayfs mount    
499 upper layer and/or workdir path the behavior o    
500 though it will not result in a crash or deadlo    
501                                                   
502 Mounting an overlay using an upper layer path,    
503 was previously used by another mounted overlay    
504 different lower layer path, is allowed, unless    
505 features are enabled.                             
506                                                   
507 With the "index" feature, on the first time mo    
508 handle of the lower layer root directory, alon    
509 filesystem, are encoded and stored in the "tru    
510 attribute on the upper layer root directory.      
511 the lower root directory file handle and lower    
512 to the stored origin in upper root directory.     
513 lower root origin, mount will fail with ESTALE    
514 "index" enabled will fail with EOPNOTSUPP if t    
515 does not support NFS export, lower filesystem     
516 if the upper filesystem does not support exten    
517                                                   
518 For the "metacopy" feature, there is no verifi    
519 mount time. So if same upper is mounted with d    
520 probably will succeed but expect the unexpecte    
521                                                   
522 It is quite a common practice to copy overlay     
523 directory tree on the same or different underl    
524 to a different machine.  With the "index" feat    
525 the copied layers will fail the verification o    
526                                                   
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                                                   
552 Non-standard behavior                             
553 ---------------------                             
554                                                   
555 Current version of overlayfs can act as a most    
556 filesystem.                                       
557                                                   
558 This is the list of cases that overlayfs doesn    
559                                                   
560  a) POSIX mandates updating st_atime for reads    
561     done in the case when the file resides on     
562                                                   
563  b) If a file residing on a lower layer is ope    
564     memory mapped with MAP_SHARED, then subseq    
565     reflected in the memory mapping.              
566                                                   
567  c) If a file residing on a lower layer is bei    
568     file for write or truncating the file will    
569                                                   
570 The following options allow overlayfs to act m    
571 compliant filesystem:                             
572                                                   
573 redirect_dir                                      
574 ````````````                                      
575                                                   
576 Enabled with the mount option or module option    
577 the kernel config option CONFIG_OVERLAY_FS_RED    
578                                                   
579 If this feature is disabled, then rename(2) on    
580 will fail with EXDEV ("Invalid cross-device li    
581                                                   
582 index                                             
583 `````                                             
584                                                   
585 Enabled with the mount option or module option    
586 kernel config option CONFIG_OVERLAY_FS_INDEX=y    
587                                                   
588 If this feature is disabled and a file with mu    
589 up, then this will "break" the link.  Changes     
590 other names referring to the same inode.          
591                                                   
592 xino                                              
593 ````                                              
594                                                   
595 Enabled with the mount option "xino=auto" or "    
596 option "xino_auto=on" or with the kernel confi    
597 CONFIG_OVERLAY_FS_XINO_AUTO=y.  Also implicitl    
598 underlying filesystem for all layers making up    
599                                                   
600 If this feature is disabled or the underlying     
601 enough free bits in the inode number, then ove    
602 guarantee that the values of st_ino and st_dev    
603 value of d_ino returned by readdir(3) will act    
604 E.g. the value of st_dev may be different for     
605 overlay filesystem and the value of st_ino for    
606 persistent and could change even while the ove    
607 summarized in the `Inode properties`_ table ab    
608                                                   
609                                                   
610 Changes to underlying filesystems                 
611 ---------------------------------                 
612                                                   
613 Changes to the underlying filesystems while pa    
614 filesystem are not allowed.  If the underlying    
615 the behavior of the overlay is undefined, thou    
616 a crash or deadlock.                              
617                                                   
618 Offline changes, when the overlay is not mount    
619 upper tree.  Offline changes to the lower tree    
620 "metacopy", "index", "xino" and "redirect_dir"    
621 have not been used.  If the lower tree is modi    
622 features has been used, the behavior of the ov    
623 though it will not result in a crash or deadlo    
624                                                   
625 When the overlay NFS export feature is enabled    
626 behavior on offline changes of the underlying     
627 than the behavior when NFS export is disabled.    
628                                                   
629 On every copy_up, an NFS file handle of the lo    
630 UUID of the lower filesystem, are encoded and     
631 attribute "trusted.overlay.origin" on the uppe    
632                                                   
633 When the NFS export feature is enabled, a look    
634 that found a lower directory at the lookup pat    
635 to by the "trusted.overlay.redirect" extended     
636 that the found lower directory file handle and    
637 match the origin file handle that was stored a    
638 found lower directory does not match the store    
639 will not be merged with the upper directory.      
640                                                   
641                                                   
642                                                   
643 NFS export                                        
644 ----------                                        
645                                                   
646 When the underlying filesystems supports NFS e    
647 feature is enabled, an overlay filesystem may     
648                                                   
649 With the "nfs_export" feature, on copy_up of a    
650 entry is created under the index directory.  T    
651 hexadecimal representation of the copy up orig    
652 non-directory object, the index entry is a har    
653 For a directory object, the index entry has an    
654 "trusted.overlay.upper" with an encoded file h    
655 directory inode.                                  
656                                                   
657 When encoding a file handle from an overlay fi    
658 following rules apply:                            
659                                                   
660  1. For a non-upper object, encode a lower fil    
661  2. For an indexed object, encode a lower file    
662  3. For a pure-upper object and for an existin    
663     encode an upper file handle from upper ino    
664                                                   
665 The encoded overlay file handle includes:         
666                                                   
667  - Header including path type information (e.g    
668  - UUID of the underlying filesystem              
669  - Underlying filesystem encoding of underlyin    
670                                                   
671 This encoding format is identical to the encod    
672 are stored in extended attribute "trusted.over    
673                                                   
674 When decoding an overlay file handle, the foll    
675                                                   
676  1. Find underlying layer by UUID and path typ    
677  2. Decode the underlying filesystem file hand    
678  3. For a lower file handle, lookup the handle    
679  4. If a whiteout is found in index, return ES    
680     overlay object that was deleted after its     
681  5. For a non-directory, instantiate a disconn    
682     decoded underlying dentry, the path type a    
683  6. For a directory, use the connected underly    
684     and index, to lookup a connected overlay d    
685                                                   
686 Decoding a non-directory file handle may retur    
687 copy_up of that disconnected dentry will creat    
688 no upper alias.                                   
689                                                   
690 When overlay filesystem has multiple lower lay    
691 directory may have a "redirect" to lower direc    
692 "redirects" are not indexed, a lower file hand    
693 "redirect" origin directory, cannot be used to    
694 layer directory.  Similarly, a lower file hand    
695 descendant of the "redirect" origin directory,    
696 reconstruct a connected overlay path.  To miti    
697 directories that cannot be decoded from a lowe    
698 directories are copied up on encode and encode    
699 On an overlay filesystem with no upper layer t    
700 used NFS export in this setup requires turning    
701 "redirect_dir=nofollow").                         
702                                                   
703 The overlay filesystem does not support non-di    
704 handles, so exporting with the 'subtree_check'    
705 cause failures to lookup files over NFS.          
706                                                   
707 When the NFS export feature is enabled, all di    
708 verified on mount time to check that upper fil    
709 This verification may cause significant overhe    
710                                                   
711 Note: the mount options index=off,nfs_export=o    
712 read-write mount and will result in an error.     
713                                                   
714 Note: the mount option uuid=off can be used to    
715 filesystem in file handles with null, and effe    
716 can be useful in case the underlying disk is c    
717 is changed. This is only applicable if all low    
718 the same filesystem, otherwise it will fallbac    
719                                                   
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                                    
746 --------------                                    
747                                                   
748 This is enabled with the "volatile" mount opti    
749 guaranteed to survive a crash.  It is strongly    
750 mounts are only used if data written to the ov    
751 without significant effort.                       
752                                                   
753 The advantage of mounting with the "volatile"     
754 sync calls to the upper filesystem are omitted    
755                                                   
756 In order to avoid a giving a false sense of sa    
757 semantics of volatile mounts are slightly diff    
758 VFS.  If any writeback error occurs on the upp    
759 volatile mount takes place, all sync functions    
760 condition is reached, the filesystem will not     
761 call will return an error, even if the upperdi    
762 since the last sync call.                         
763                                                   
764 When overlay is mounted with "volatile" option    
765 "$workdir/work/incompat/volatile" is created.     
766 checks for this directory and refuses to mount    
767 indicator that user should throw away upper an    
768 fresh one. In very limited cases where the use    
769 not crashed and contents of upperdir are intac    
770 can be removed.                                   
771                                                   
772                                                   
773 User xattr                                        
774 ----------                                        
775                                                   
776 The "-o userxattr" mount option forces overlay    
777 "user.overlay." xattr namespace instead of "tr    
778 useful for unprivileged mounting of overlayfs.    
779                                                   
780                                                   
781 Testsuite                                         
782 ---------                                         
783                                                   
784 There's a testsuite originally developed by Da    
785 maintained by Amir Goldstein at:                  
786                                                   
787 https://github.com/amir73il/unionmount-testsui    
788                                                   
789 Run as root::                                     
790                                                   
791   # cd unionmount-testsuite                       
792   # ./run --ov --verify                           
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php