Received-SPF: pass (google.com: domain of linux-nfs-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   "Benjamin Coddington" <bcodding@redhat.com>
To:     NeilBrown <neilb@suse.de>
Cc:     "Steve Dickson" <SteveD@RedHat.com>,
        "Chuck Lever III" <chuck.lever@oracle.com>,
        "Linux NFS Mailing List" <linux-nfs@vger.kernel.org>,
        "Trond Myklebust" <trondmy@hammerspace.com>
Subject: Re: [PATCH v2] nfs.man: document requirements for NFSv4 identity
Date:   Mon, 14 Mar 2022 09:48:42 -0400
Message-ID: <8EF0A369-CDE5-4FA1-9085-A6BB96C711C8@redhat.com>
In-Reply-To: <164721984672.11933.15475930163427511814@noble.neil.brown.name>
References: <164721984672.11933.15475930163427511814@noble.neil.brown.name>
MIME-Version: 1.0
Content-Type: text/plain; format=flowed
Precedence: bulk

On 13 Mar 2022, at 21:04, NeilBrown wrote:

> When mounting NFS filesystem in a network namespace using v4, some 
> care
> must be taken to ensure a unique and stable client identity.  Similar
> case is needed for NFS-root and other situations.
>
> Add documentation explaining the requirements for the NFS identity in
> these situations.
>
> Signed-off-by: NeilBrown <neilb@suse.de>
> ---
>
> I think I've address most of the feedback, but please forgive and 
> remind
> if I missed something.
> NeilBrown
>
>  utils/mount/nfs.man | 109 
> +++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 108 insertions(+), 1 deletion(-)
>
> diff --git a/utils/mount/nfs.man b/utils/mount/nfs.man
> index d9f34df36b42..5f15abe8cf72 100644
> --- a/utils/mount/nfs.man
> +++ b/utils/mount/nfs.man
> @@ -1,7 +1,7 @@
>  .\"@(#)nfs.5"
>  .TH NFS 5 "9 October 2012"
>  .SH NAME
> -nfs \- fstab format and options for the
> +nfs \- fstab format and configuration for the
>  .B nfs
>  file systems
>  .SH SYNOPSIS
> @@ -1844,6 +1844,113 @@ 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 CLIENT IDENTIFIER"
> +NFSv4 requires that the client present a unique identifier to the 
> server
> +to be used to track state such as file locks.  By default Linux NFS 
> uses
> +the host name, as configured at the time of the first NFS mount,
> +together with some fixed content such as the name "Linux NFS" and the
> +particular protocol version.  When the hostname is guaranteed to be
> +unique among all client which access the same server this is 
> sufficient.
> +If hostname uniqueness cannot be assumed, extra identity information
> +must be provided.
> +.PP
> +Some situations which are known to be problematic with respect to 
> unique
> +host names include:
> +.IP \- 2
> +NFS-root (diskless) clients, where the DCHP server (or equivalent) 
> does
> +not provide a unique host name.
> +.IP \- 2
> +"containers" within a single Linux host.  If each container has a 
> separate
> +network namespace, but does not use the UTS namespace to provide a 
> unique
> +host name, then there can be multiple effective NFS clients with the
> +same host name.
> +.IP \= 2
> +Clients across multiple administrative domains that access a common 
> NFS
> +server.  If assignment of host name is devolved to separate domains,
> +uniqueness cannot be guaranteed, unless a domain name is included in 
> the
> +host name.
> +.SS "Increasing Client Uniqueness"
> +Apart from the host name, which is the preferred way to differentiate
> +NFS clients, there are two mechanisms to add uniqueness to the
> +client identifier.
> +.TP
> +.B nfs.nfs4_unique_id
> +This module parameter can be set to an arbitrary string at boot time, 
> or
> +when the
> +.B nfs
> +module is loaded.  This might be suitable for configuring diskless 
> clients.
> +.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

+name-space in which it is accessed and so can provided uniqueness 
between
+name-space in which it is accessed and so can provide uniqueness 
between
                                                       ^

> +network namespaces (containers) when the hostname remains uniform.
> +.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.  If the container system has access to some sort of 
> per-container
> +identity then that identity, possibly obfuscated as a UUID is privacy 
> is

+identity then that identity, possibly obfuscated as a UUID is privacy 
is
+identity then that identity, possibly obfuscated as a UUID if privacy 
is
                                                             ^^

> +needed, can be used.  Combining the identity with the name of the
> +container systems would also help.  For example:
> +.RS 4
> +echo "ip-netns:`ip netns identify`" \\
> +.br
> +   > /sys/fs/nfs/client/net/identifier
> +.br
> +uuidgen --sha1 --namespace @url  \\
> +.br
> +   -N "nfs:`cat /etc/machine-id`" \\
> +.br
> +   > /sys/fs/nfs/client/net/identifier
> +.RE
> +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 identifier to ensure uniqueness would be best
> +.RS 4
> +uuidgen > /sys/fs/nfs/client/net/identifier
> +.RE
> +.RE
> +.SS Consequences of poor identity setting
> +Any two concurrent clients that might access the same server must 
> have
> +different identifiers for correct operation, and any two consecutive
> +instances of the same client should have the same identifier for 
> optimal
> +crash recovery.
> +.PP
> +If two different clients present the same identity to a server there 
> are
> +two possible scenarios.  If the clients use the same credential then 
> the
> +server will treat them as the same client which appears to be 
> restarting
> +frequently.  One client may manage to open some files etc, but as 
> soon
> +as the other client does anything the first client will lose access 
> and
> +need to re-open everything.
> +.PP
> +If the clients use different credentials, then the second client to
> +establish a connection to the server will be refused access.  For
> +.B auth=sys
> +the credential is based on hostname, so will be the same if the
> +identities are the same.  With
> +.B auth=krb
> +the credential is stored in
> +.I /etc/krb5.keytab
> +and will be the same only if this is copied among hosts.
> +.PP
> +If the identity is unique but not stable, for example if it is 
> generated
> +randomly on each start up of the NFS client, then crash recovery is
> +affected.  When a client shuts down uncleanly and restarts, the 
> server
> +will normally detect this because the same identity is presented with

There's ambiguity on "this", it could be the situation described in the
previous sentence, how about:

+will normally detect this because the same identity is presented with
+will normally detect the unclean restart because the same identity is 
presented with

Ben