217 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=======================4NFSv4 client identifier5=======================6 7This document explains how the NFSv4 protocol identifies client8instances in order to maintain file open and lock state during9system restarts. A special identifier and principal are maintained10on each client. These can be set by administrators, scripts11provided by site administrators, or tools provided by Linux12distributors.13 14There are risks if a client's NFSv4 identifier and its principal15are not chosen carefully.16 17 18Introduction19------------20 21The NFSv4 protocol uses "lease-based file locking". Leases help22NFSv4 servers provide file lock guarantees and manage their23resources.24 25Simply put, an NFSv4 server creates a lease for each NFSv4 client.26The server collects each client's file open and lock state under27the lease for that client.28 29The client is responsible for periodically renewing its leases.30While a lease remains valid, the server holding that lease31guarantees the file locks the client has created remain in place.32 33If a client stops renewing its lease (for example, if it crashes),34the NFSv4 protocol allows the server to remove the client's open35and lock state after a certain period of time. When a client36restarts, it indicates to servers that open and lock state37associated with its previous leases is no longer valid and can be38destroyed immediately.39 40In addition, each NFSv4 server manages a persistent list of client41leases. When the server restarts and clients attempt to recover42their state, the server uses this list to distinguish amongst43clients that held state before the server restarted and clients44sending fresh OPEN and LOCK requests. This enables file locks to45persist safely across server restarts.46 47NFSv4 client identifiers48------------------------49 50Each NFSv4 client presents an identifier to NFSv4 servers so that51they can associate the client with its lease. Each client's52identifier consists of two elements:53 54 - co_ownerid: An arbitrary but fixed string.55 56 - boot verifier: A 64-bit incarnation verifier that enables a57 server to distinguish successive boot epochs of the same client.58 59The NFSv4.0 specification refers to these two items as an60"nfs_client_id4". The NFSv4.1 specification refers to these two61items as a "client_owner4".62 63NFSv4 servers tie this identifier to the principal and security64flavor that the client used when presenting it. Servers use this65principal to authorize subsequent lease modification operations66sent by the client. Effectively this principal is a third element of67the identifier.68 69As part of the identity presented to servers, a good70"co_ownerid" string has several important properties:71 72 - The "co_ownerid" string identifies the client during reboot73 recovery, therefore the string is persistent across client74 reboots.75 - The "co_ownerid" string helps servers distinguish the client76 from others, therefore the string is globally unique. Note77 that there is no central authority that assigns "co_ownerid"78 strings.79 - Because it often appears on the network in the clear, the80 "co_ownerid" string does not reveal private information about81 the client itself.82 - The content of the "co_ownerid" string is set and unchanging83 before the client attempts NFSv4 mounts after a restart.84 - The NFSv4 protocol places a 1024-byte limit on the size of the85 "co_ownerid" string.86 87Protecting NFSv4 lease state88----------------------------89 90NFSv4 servers utilize the "client_owner4" as described above to91assign a unique lease to each client. Under this scheme, there are92circumstances where clients can interfere with each other. This is93referred to as "lease stealing".94 95If distinct clients present the same "co_ownerid" string and use96the same principal (for example, AUTH_SYS and UID 0), a server is97unable to tell that the clients are not the same. Each distinct98client presents a different boot verifier, so it appears to the99server as if there is one client that is rebooting frequently.100Neither client can maintain open or lock state in this scenario.101 102If distinct clients present the same "co_ownerid" string and use103distinct principals, the server is likely to allow the first client104to operate normally but reject subsequent clients with the same105"co_ownerid" string.106 107If a client's "co_ownerid" string or principal are not stable,108state recovery after a server or client reboot is not guaranteed.109If a client unexpectedly restarts but presents a different110"co_ownerid" string or principal to the server, the server orphans111the client's previous open and lock state. This blocks access to112locked files until the server removes the orphaned state.113 114If the server restarts and a client presents a changed "co_ownerid"115string or principal to the server, the server will not allow the116client to reclaim its open and lock state, and may give those locks117to other clients in the meantime. This is referred to as "lock118stealing".119 120Lease stealing and lock stealing increase the potential for denial121of service and in rare cases even data corruption.122 123Selecting an appropriate client identifier124------------------------------------------125 126By default, the Linux NFSv4 client implementation constructs its127"co_ownerid" string starting with the words "Linux NFS" followed by128the client's UTS node name (the same node name, incidentally, that129is used as the "machine name" in an AUTH_SYS credential). In small130deployments, this construction is usually adequate. Often, however,131the node name by itself is not adequately unique, and can change132unexpectedly. Problematic situations include:133 134 - NFS-root (diskless) clients, where the local DHCP server (or135 equivalent) does not provide a unique host name.136 137 - "Containers" within a single Linux host. If each container has138 a separate network namespace, but does not use the UTS namespace139 to provide a unique host name, then there can be multiple NFS140 client instances with the same host name.141 142 - Clients across multiple administrative domains that access a143 common NFS server. If hostnames are not assigned centrally144 then uniqueness cannot be guaranteed unless a domain name is145 included in the hostname.146 147Linux provides two mechanisms to add uniqueness to its "co_ownerid"148string:149 150 nfs.nfs4_unique_id151 This module parameter can set an arbitrary uniquifier string152 via the kernel command line, or when the "nfs" module is153 loaded.154 155 /sys/fs/nfs/net/nfs_client/identifier156 This virtual file, available since Linux 5.3, is local to the157 network namespace in which it is accessed and so can provide158 distinction between network namespaces (containers) when the159 hostname remains uniform.160 161Note that this file is empty on name-space creation. If the162container system has access to some sort of per-container identity163then that uniquifier can be used. For example, a uniquifier might164be formed at boot using the container's internal identifier:165 166 sha256sum /etc/machine-id | awk '{print $1}' \\167 > /sys/fs/nfs/net/nfs_client/identifier168 169Security considerations170-----------------------171 172The use of cryptographic security for lease management operations173is strongly encouraged.174 175If NFS with Kerberos is not configured, a Linux NFSv4 client uses176AUTH_SYS and UID 0 as the principal part of its client identity.177This configuration is not only insecure, it increases the risk of178lease and lock stealing. However, it might be the only choice for179client configurations that have no local persistent storage.180"co_ownerid" string uniqueness and persistence is critical in this181case.182 183When a Kerberos keytab is present on a Linux NFS client, the client184attempts to use one of the principals in that keytab when185identifying itself to servers. The "sec=" mount option does not186control this behavior. Alternately, a single-user client with a187Kerberos principal can use that principal in place of the client's188host principal.189 190Using Kerberos for this purpose enables the client and server to191use the same lease for operations covered by all "sec=" settings.192Additionally, the Linux NFS client uses the RPCSEC_GSS security193flavor with Kerberos and the integrity QOS to prevent in-transit194modification of lease modification requests.195 196Additional notes197----------------198The Linux NFSv4 client establishes a single lease on each NFSv4199server it accesses. NFSv4 mounts from a Linux NFSv4 client of a200particular server then share that lease.201 202Once a client establishes open and lock state, the NFSv4 protocol203enables lease state to transition to other servers, following data204that has been migrated. This hides data migration completely from205running applications. The Linux NFSv4 client facilitates state206migration by presenting the same "client_owner4" to all servers it207encounters.208 209========210See Also211========212 213 - nfs(5)214 - kerberos(7)215 - RFC 7530 for the NFSv4.0 specification216 - RFC 8881 for the NFSv4.1 specification.217