[14/14] ovl: document NFS export

Commit Message

Amir Goldstein Oct. 17, 2017, 4:44 p.m. UTC

Signed-off-by: Amir Goldstein <[e-mail]>
---
 Documentation/filesystems/overlayfs.txt | 61 +++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

Patch

diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt
index d89041baceb9..dbd829b0b12b 100644
--- a/Documentation/filesystems/overlayfs.txt
+++ b/Documentation/filesystems/overlayfs.txt
@@ -285,6 +285,67 @@  merged with the upper directory instead.  The "verify_dir" feature,
 therefore, makes an overlay mount cope better with the situations of
 lower directory rename and delete.
 
+
+NFS export
+----------
+
+An overlay filesystem may be exported to NFS when:
+- All underlying filesystems support NFS file handles
+- overlay is mounted with the mount options "index=all,verify_dir"
+- overlay is not using multiple lower layers
+
+With the "index=all" 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.overlay.origin" with an encoded file handle of the upper
+directory inode.
+
+When encoding a file handle from an overlay filesystem object, the
+following rules apply:
+
+1. For a non-upper object, encode a lower file handle from lower inode
+2. For a pure-upper object, encode an upper file handle from upper inode
+3. For an indexed object, encode a lower file handle from copy_up origin
+
+Encoding a lower directory file handle will copy up and index that
+directory, so the index can be use on decode to find the upper directory.
+An existing non-indexed merged directory cannot be encoded with current
+NFS export implementation.
+
+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
+
+This encoding is identical to the encoding of copy_up origin stored in
+"trusted.overlay.origin".
+
+When decoding an overlay file handle, the following steps are followed:
+
+1. Find underlying layer by UUID and path type information.
+2. Decode the underlying filesystem file handle to underlying dentry.
+3. Lookup the file handle in index directory by name.
+4. If not found in index, instantiate an overlay dentry from the decoded
+   lower dentry.
+6. If a non-directory is found in index, instantiate a disconnected overlay
+   dentry from the upper index dentry and the decoded lower dentry.
+5. If a directory is found in index, decode upper dentry from file handle
+   stored in extended attribute "trusted.overlay.origin" in the index and
+   instantiate an overlay dentry from the decoded upper and lower dentries.
+7. If a whiteout is found in index, return ESTALE. This represents an
+   overlay object that was deleted after its file handle was encoded.
+
+The "verify_dir" mount option and no multiple lower layer requirements,
+ensure that a decoded overlay directory object will be equivalent to the
+object that was used to encode the file handle.
+
+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.
+
+
 Testsuite
 ---------