Commit d17bb462 authored by Amir Goldstein's avatar Amir Goldstein
Browse files

overlayfs.rst: fix ReST formatting 



Fix some indentation issues and fix missing newlines in quoted text
by converting quoted text to code blocks.

Reported-by: default avatarChristian Brauner <brauner@kernel.org>
Suggested-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: default avatarAkira Yokosawa <akiyks@gmail.com>
Signed-off-by: default avatarAmir Goldstein <amir73il@gmail.com>
parent bdc10bdf

Documentation/filesystems/overlayfs.rst

+39 −38
Original line number Diff line number Diff line
@@ -118,7 +118,7 @@ Where both upper and lower objects are directories, a merged directory 
is formed.



At mount time, the two directories given as mount options "lowerdir" and

"upperdir" are combined into a merged directory:

"upperdir" are combined into a merged directory::



  mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\

  workdir=/work /merged
@@ -172,7 +172,7 @@ directory is being read. This is unlikely to be noticed by many 
programs.



seek offsets are assigned sequentially when the directories are read.

Thus if

Thus if:



 - read part of a directory

 - remember an offset, and close the directory
@@ -292,7 +292,7 @@ Permission checking in the overlay filesystem follows these principles: 
 3) non-mounting task MAY gain additional privileges through the overlay,

    compared to direct access on underlying lower or upper filesystems



This is achieved by performing two permission checks on each access

This is achieved by performing two permission checks on each access:



 a) check if current task is allowed access based on local DAC (owner,

    group, mode and posix acl), as well as MAC checks
@@ -311,11 +311,11 @@ to create setups where the consistency rule (1) does not hold; normally, 
however, the mounting task will have sufficient privileges to perform all

operations.



Another way to demonstrate this model is drawing parallels between

Another way to demonstrate this model is drawing parallels between::



  mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,... /merged



and

and::



  cp -a /lower /upper

  mount --bind /upper /merged
@@ -328,7 +328,7 @@ Multiple lower layers 
---------------------



Multiple lower layers can now be given using the colon (":") as a

separator character between the directory names.  For example:

separator character between the directory names.  For example::



  mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged
@@ -340,13 +340,13 @@ rightmost one and going left. In the above example lower1 will be the 
top, lower2 the middle and lower3 the bottom layer.



Note: directory names containing colons can be provided as lower layer by

escaping the colons with a single backslash.  For example:

escaping the colons with a single backslash.  For example::



  mount -t overlay overlay -olowerdir=/a\:lower\:\:dir /merged



Since kernel version v6.8, directory names containing colons can also

be configured as lower layer using the "lowerdir+" mount options and the

fsconfig syscall from new mount api.  For example:

fsconfig syscall from new mount api.  For example::



  fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/a:lower::dir", 0);
@@ -405,7 +405,7 @@ A normal lower layer is not allowed to be below a data-only layer, so single 
colon separators are not allowed to the right of double colon ("::") separators.





For example:

For example::



  mount -t overlay overlay -olowerdir=/l1:/l2:/l3::/do1::/do2 /merged
@@ -419,7 +419,7 @@ to the absolute path of the "lower data" file in the "data-only" lower layer. 


Since kernel version v6.8, "data-only" lower layers can also be added using

the "datadir+" mount options and the fsconfig syscall from new mount api.

For example:

For example::



  fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l1", 0);

  fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/l2", 0);
@@ -429,7 +429,7 @@ For example: 




fs-verity support

----------------------

-----------------



During metadata copy up of a lower file, if the source file has

fs-verity enabled and overlay verity support is enabled, then the
@@ -653,6 +653,7 @@ following rules apply: 
    encode an upper file handle from upper inode



The encoded overlay file handle includes:



 - Header including path type information (e.g. lower/upper)

 - UUID of the underlying filesystem

 - Underlying filesystem encoding of underlying inode
@@ -775,7 +776,7 @@ maintained by Amir Goldstein at: 


https://github.com/amir73il/unionmount-testsuite.git



Run as root:

Run as root::



  # cd unionmount-testsuite

  # ./run --ov --verify