When mounting NFS filesystems in a network namespace using v4, some care must be taken to ensure a unique and stable client identity. Add documentation explaining the requirements for container managers. Signed-off-by: NeilBrown <neilb@xxxxxxx> --- NOTE I originally suggested using uuidgen to generate a uuid from a container name. I've changed it to use the name as-is because I cannot see a justification for using a uuid - though I think that was suggested somewhere in the discussion. If someone would like to provide that justification, I'm happy to include it in the document. Thanks, NeilBrown utils/mount/nfs.man | 63 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/utils/mount/nfs.man b/utils/mount/nfs.man index d9f34df36b42..4ab76fb2df91 100644 --- a/utils/mount/nfs.man +++ b/utils/mount/nfs.man @@ -1844,6 +1844,69 @@ export pathname, but not both, during a remount. For example, merges the mount option .B ro with the mount options already saved on disk for the NFS server mounted at /mnt. +.SH "NFS IN A CONTAINER" +When NFS is used to mount filesystems in a container, and specifically +in a separate network name-space, these mounts are treated as quite +separate from any mounts in a different container or not in a +container (i.e. in a different network name-space). +.P +In the NFSv4 protocol, each client must have a unique identifier. +This is used by the server to determine when a client has restarted, +allowing any state from a previous instance can be discarded. So any two +concurrent clients that might access the same server MUST have +different identifiers, and any two consecutive instances of the same +client SHOULD have the same identifier. +.P +Linux constructs the identifier (referred to as +.B co_ownerid +in the NFS specifications) from various pieces of information, three of +which can be controlled by the sysadmin: +.TP +Hostname +The hostname can be different in different containers if they +have different "UTS" name-spaces. If the container system ensures +each container sees a unique host name, then this is +sufficient for a correctly functioning NFS identifier. +The host name is copied when the first NFS filesystem is mounted in +a given network name-space. Any subsequent change in the apparent +hostname will not change the NFSv4 identifier. +.TP +.B nfs.nfs4_unique_id +This module parameter is the same for all containers on a given host +so it is not useful to differentiate between containers. +.TP +.B /sys/fs/nfs/client/net/identifier +This virtual file (available since Linux 5.3) is local to the network +name-space in which it is accessed and so can provided uniqueness between +containers when the hostname is uniform among containers. +.RS +.PP +This value is empty on name-space creation. +If the value is to be set, that should be done before the first +mount (much as the hostname is copied before the first mount). +If the container system has access to some sort of per-container +identity, then a command like +.RS 4 +echo "$CONTAINER_IDENTITY" \\ +.br + > /sys/fs/nfs/client/net/identifier +.RE +might be suitable. If the container system provides no stable name, +but does have stable storage, then something like +.RS 4 +[ -s /etc/nfsv4-uuid ] || uuidgen > /etc/nfsv4-uuid && +.br +cat /etc/nfsv4-uuid > /sys/fs/nfs/client/net/identifier +.RE +would suffice. +.PP +If a container has neither a stable name nor stable (local) storage, +then it is not possible to provide a stable identifier, so providing +a random one to ensure uniqueness would be best +.RS 4 +uuidgen > /sys/fs/nfs/client/net/identifier +.RE +.RE .SH FILES .TP 1.5i .I /etc/fstab -- 2.35.1
