ovl: document NFS export

NFS export support on an overlay filesystem with no upper layer requires

turning off redirect follow (e.g. "redirect_dir=nofollow").

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.

Non-directories

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

will not be merged with the upper directory.

NFS export

----------

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.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:

1. For a non-upper object, encode a lower file handle from lower inode

2. For an indexed object, encode a lower file handle from copy_up origin

3. For a pure-upper object and for an existing non-indexed upper object,

   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

This encoding format is identical to the encoding format file handles that

are stored in extended attribute "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. For a lower file handle, lookup the handle in index directory by name.

4. If a whiteout is found in index, return ESTALE. This represents an

   overlay object that was deleted after its file handle was encoded.

5. For a non-directory, instantiate a disconnected overlay dentry from the

   decoded underlying dentry, the path type and index inode, if found.

6. 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").

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.

Testsuite

---------