ericonr
/
util-linux
mirror of https://github.com/ericonr/util-linux.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

mount.8: fix overlayfs nfs_export= indention 

Signed-off-by: Karel Zak <kzak@redhat.com>
This commit is contained in:
Karel Zak 2021-06-18 14:37:28 +02:00
parent 627fb946d5
commit 0197bdb2d0
1 changed files with 51 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
sys-utils/mount.8.adoc
View File

@ -1038,60 +1038,82 @@ Inode index. If this feature is disabled and a file with multiple hard links is
Can be used to replace UUID of the underlying filesystem in file handles with null, and effectively disable UUID checks. This can be useful in case the underlying disk is copied and the UUID of this copy is changed. This is only applicable if all lower/upper/work directories are on the same filesystem, otherwise it will fallback to normal behaviour.
*nfs_export=*{**on**|**off**}::
When the underlying filesystems supports NFS export and the "nfs_export" feature is enabled, an overlay filesystem may be exported to NFS.
When the underlying filesystems supports NFS export and the "nfs_export"
feature is enabled, an overlay filesystem may be exported to NFS.
+
With the “nfs_export” feature, on copy_up of any lower object, an index entry
is created under the index directory. The index entry name is the hexadecimal
representation of the copy up origin file handle. For a non-directory object,
the index entry is a hard link to the upper inode. For a directory object, the
index entry has an extended attribute "{**trusted**|**user**}.overlay.upper"
with an encoded file handle of the upper directory inode.
+
When encoding a file handle from an overlay filesystem object, the following rules apply;;
With the “nfs_export” feature, on copy_up of any lower object, an index entry is created under the index directory. The index entry name is the hexadecimal representation of the copy up origin file handle. For a non-directory object, the index entry is a hard link to the upper inode. For a directory object, the index entry has an extended attribute "{**trusted**|**user**}.overlay.upper" with an encoded file handle of the upper directory inode.
* For a non-upper object, encode a lower file handle from lower inode
* For an indexed object, encode a lower file handle from copy_up origin
* For a pure-upper object and for an existing non-indexed upper object, encode an upper file handle from upper inode
When encoding a file handle from an overlay filesystem object, the following rules apply:
+
The encoded overlay file handle includes;;
. For a non-upper object, encode a lower file handle from lower inode
. For an indexed object, encode a lower file handle from copy_up origin
. For a pure-upper object and for an existing non-indexed upper object, encode an upper file handle from upper inode
* Header including path type information (e.g. lower/upper)
* UUID of the underlying filesystem
* Underlying filesystem encoding of underlying inode
*The encoded overlay file handle includes*:
+
This encoding format is identical to the encoding format file handles that are stored in extended attribute "{**trusted**|**user**}.overlay.origin". When decoding an overlay file handle, the following steps are followed;;
- Header including path type information (e.g. lower/upper)
- UUID of the underlying filesystem
- Underlying filesystem encoding of underlying inode
* Find underlying layer by UUID and path type information.
* Decode the underlying filesystem file handle to underlying dentry.
* For a lower file handle, lookup the handle in index directory by name.
* If a whiteout is found in index, return ESTALE. This represents an overlay object that was deleted after its file handle was encoded.
* For a non-directory, instantiate a disconnected overlay dentry from the decoded underlying dentry, the path type and index inode, if found.
* For a directory, use the connected underlying decoded dentry, path type and index, to lookup a connected overlay dentry.
This encoding format is identical to the encoding format file handles that are stored in extended attribute "{**trusted**|**user**}.overlay.origin".
+
--
Decoding a non-directory file handle may return a disconnected dentry. copy_up
of that disconnected dentry will create an upper index entry with no upper
alias.
When decoding an overlay file handle, the following steps are followed:
. Find underlying layer by UUID and path type information.
. Decode the underlying filesystem file handle to underlying dentry.
. For a lower file handle, lookup the handle in index directory by name.
. If a whiteout is found in index, return ESTALE. This represents an overlay object that was deleted after its file handle was encoded.
. For a non-directory, instantiate a disconnected overlay dentry from the decoded underlying dentry, the path type and index inode, if found.
. For a directory, use the connected underlying decoded dentry, path type and index, to lookup a connected overlay dentry.
Decoding a non-directory file handle may return a disconnected dentry. copy_up of that disconnected dentry will create an upper index entry with no upper alias.
When overlay filesystem has multiple lower layers, a middle layer directory may have a "redirect" to lower directory. Because middle layer "redirects" are not indexed, a lower file handle that was encoded from the "redirect" origin directory, cannot be used to find the middle or upper layer directory. Similarly, a lower file handle that was encoded from a descendant of the "redirect" origin directory, cannot be used to reconstruct a connected overlay path. To mitigate the cases of directories that cannot be decoded from a lower file handle, these directories are copied up on encode and encoded as an upper file handle. On an overlay filesystem with no upper layer this mitigation cannot be used NFS export in this setup requires turning off redirect follow (e.g. "__redirect_dir=nofollow__").
When overlay filesystem has multiple lower layers, a middle layer directory may
have a "redirect" to lower directory. Because middle layer "redirects" are not
indexed, a lower file handle that was encoded from the "redirect" origin
directory, cannot be used to find the middle or upper layer directory.
Similarly, a lower file handle that was encoded from a descendant of the
"redirect" origin directory, cannot be used to reconstruct a connected overlay
path. To mitigate the cases of directories that cannot be decoded from a lower
file handle, these directories are copied up on encode and encoded as an upper
file handle. On an overlay filesystem with no upper layer this mitigation
cannot be used NFS export in this setup requires turning off redirect follow
(e.g. "__redirect_dir=nofollow__").
The overlay filesystem does not support non-directory connectable file handles, so exporting with the _subtree_check_ exportfs configuration will cause failures to lookup files over NFS.
When the NFS export feature is enabled, all directory index entries are verified on mount time to check that upper file handles are not stale. This verification may cause significant overhead in some cases.
Note: the mount options __index=off,nfs_export=on__ are conflicting for a read-write mount and will result in an error.
Note: the mount options __index=off,nfs_export=on__ are conflicting for a
read-write mount and will result in an error.
--
*xinfo=*{**on**|**off**|**auto**}::
The "xino" feature composes a unique object identifier from the real object st_ino and an underlying fsid index. The "xino" feature uses the high inode number bits for fsid, because the underlying filesystems rarely use the high inode number bits. In case the underlying inode number does overflow into the high xino bits, overlay filesystem will fall back to the non xino behavior for that inode.
+
For a detailed description of the effect of this option please refer to https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html?highlight=overlayfs
*metacopy=*{**on**|**off**}::
When metadata only copy up feature is enabled, overlayfs will only copy up metadata (as opposed to whole file), when a metadata specific operation like chown/chmod is performed. Full file will be copied up later when file is opened for WRITE operation.
+
In other words, this is delayed data copy up operation and data is copied up when there is a need to actually modify data.
*volatile*::
Volatile mounts are not guaranteed to survive a crash. It is strongly recommended that volatile mounts are only used if data written to the overlay can be recreated without significant effort.
+
The advantage of mounting with the "volatile" option is that all forms of sync calls to the upper filesystem are omitted.
+
In order to avoid a giving a false sense of safety, the syncfs (and fsync) semantics of volatile mounts are slightly different than that of the rest of VFS. If any writeback error occurs on the upperdir’s filesystem after a volatile mount takes place, all sync functions will return an error. Once this condition is reached, the filesystem will not recover, and every subsequent sync call will return an error, even if the upperdir has not experience a new error since the last sync call.
+
When overlay is mounted with "volatile" option, the directory "$workdir/work/incompat/volatile" is created. During next mount, overlay checks for this directory and refuses to mount if present. This is a strong indicator that user should throw away upper and work directories and create fresh one. In very limited cases where the user knows that the system has not crashed and contents of upperdir are intact, The "volatile" directory can be removed.
=== Mount options for reiserfs