NFSv4.0 Migration: Specification Update

Implementation experience with transparent state migration revealed three problems in RFC 7530: client reboots after migration did not promptly free old state; a server could end up with multiple leases sharing the same nfs_client_id4 (violating the one-lease-per-client assumption); and clients had to manage locking state split across multiple clientid4s. The root cause was that prior specs required transferring clientid4s without defining how migrated state integrates with existing leases on the destination server.

NFSv4.0 supports two client ID string construction approaches: 'non-uniform' (different id strings per server address, one clientid4/lease per IP, NFSv3-like) and 'uniform' (same id string to all servers, enabling server trunking detection and automatic lease merger on migration). Clients supporting transparent state migration are recommended to use the uniform approach because it enables the destination server to perform lease merger without client involvement.

The distinguishing characteristic between reboot-like clientid4 invalidity and migration-related invalidity is that in reboot-like cases both the clientid4 and all associated stateids cease to exist, while in migration-related cases only the clientid4 ceases to exist on the source server and the stateids are still valid on the destination. Clients must use this distinction to select the appropriate recovery procedure.

The non-uniform client ID string approach presents a different id string to each server network address, resulting in a separate clientid4/lease per server IP. This mirrors NFSv3 behavior and simplifies the client, but is discouraged for clients supporting transparent state migration because migrating leases can result in multiple leases for the same client on the same server, vitiating the approach's advantages.

The uniform client ID string approach presents the same id string to all servers, giving the server the basis for a single clientid4/lease per distinct client. Within this approach, the verifier field (boot instance id) must change if and only if a new client instance is created (typically on reboot), so clients should establish the verifier once per reboot rather than recreating it each time an (IP-address, clientid4) tracking structure is destroyed and recreated.

Some existing NFSv4.0 servers that implement IP address failover rely on the non-uniform client ID string approach to keep separate state corpora distinct; others incorrectly return NFS4ERR_CLID_INUSE when a multihomed client using the uniform approach presents the same id string from a second IP address. Clients may need to support both approaches simultaneously (selected per-mount via mount options) to interoperate with such servers.

When multiple file systems are migrated in sequence to the same destination server, an owner may arrive at a destination where it already exists, requiring merger of owner sequence values. The resulting sequence value must be the greater of the two; neither prior reply record may be discarded until the client has demonstrably received it. Servers may decline to transfer such state rather than implement the merger logic.

After migration where leases are not merged, the client SHOULD re-establish callback information with the new server as soon as possible using SETCLIENTID/SETCLIENTID_CONFIRM. This prevents unwanted revocation of existing delegations caused by the server's inability to recall them due to missing callback information.

If the destination server already has a lease whose nfs_client_id4 (id string and boot verifier) exactly matches a migrated lease, the server SHOULD merge the two leases into one, making the union of their stateids available under the existing clientid4. The merged lease expiration time reflects the latest renewal of either ancestor lease.

If the destination server has a lease with the same id string but a different boot verifier from a migrated lease (partial match), the server MUST eliminate one of the two conflicting leases. Since boot instance ids are not ordered, the lease with the later renewal time prevails, and the other clientid4 is invalidated.

If transferring stateids would result in a conflict with an existing stateid on the destination server for the same client, transparent state migration MUST NOT happen for that client. Servers using transparent state migration should coordinate stateid assignment policies to make such conflicts unlikely or impossible.

In the case of migration with state transfer, the transfer MUST be done in a way that is transparent to the client. The new server must recognize stateids from the original server as valid and treat them as representing the same locks — same file, same lock type (open, delegation, advisory byte-range, mandatory byte-range), same particulars (access/deny modes, byte ranges), and same owner strings.

Servers MUST NOT assign different clientid4 values to the same client (presenting the same nfs_client_id4) on different IP addresses and then act as if those clientid4s belong to the same client. This behavior would defeat the primary purpose of the trunking determination algorithm and is the only server behavior that can cause the algorithm to fail.

Servers MUST NOT reject an nfs_client_id4 simply because the id string does not follow the rules of UTF-8 encoding. Although the id field is often called a string, it is defined by the protocol as opaque data and must be treated as such.

To prevent malicious destruction of locking state, the server MUST NOT cancel a client's leased state if the principal that established the state for a given id string is not the same as the principal issuing the SETCLIENTID. This prevents unauthorized lease cancellation by a different security principal.

security

When a server holds an owner sequence value that matches a reissued request, it MUST NOT respond with the stored associated response if the file system associated with that stored response is not currently part of the set of file systems handled by that server. This prevents stale responses from being returned for file systems that have since migrated away.

When a server implements migration but chooses not to transfer state information, it MUST provide a file-system-specific grace period to allow clients to reclaim locks associated with files in the migrated file system. Without this grace period, clients cannot guarantee that no conflicting lock was granted after migration but before their re-acquisition.

When constructing the client ID string, any values that may change over time (IP address, MAC address, etc.) SHOULD be captured as saved copies rather than re-derived dynamically, or the entire constructed string should be saved and reused, to prevent the id string from changing across SETCLIENTID invocations within the same client incarnation.

When the server gets a SETCLIENTID for a client ID string whose existing lease has no state or whose lease has expired, even under an apparent change of principal, the server MUST allow the SETCLIENTID rather than returning NFS4ERR_CLID_INUSE, and MUST confirm the new client ID if followed by the appropriate SETCLIENTID_CONFIRM.

Use of the uniform client ID string approach enables multiple servers acting in concert to determine when multiple requests received at different times originate from the same NFSv4.0 client, potentially correlating distinct user identities to the same person across different servers. Client implementers must weigh this privacy exposure against the operational benefits of the uniform approach.

privacy

During migration, servers must transfer open-owner and lock-owner state including: the sequence number of the last operation per owner and sufficient result information to correctly respond to reissued operations. When an owner's state spans multiple file systems, the owner sequence value is propagated to the destination while retained on the source; both servers advance the sequence independently thereafter, potentially requiring support for multiple 'last reply' data items per owner.

The clientid4 is a 64-bit shorthand identifier assigned by the server after a successful SETCLIENTID/SETCLIENTID_CONFIRM sequence. It becomes invalid upon server reboot (NFS4ERR_STALE_CLIENTID), lease expiration (NFS4ERR_EXPIRED), administrative revocation (NFS4ERR_ADMIN_REVOKED), migration of all associated state (NFS4ERR_STALE_CLIENTID), or merger with another lease (NFS4ERR_STALE_CLIENTID). In migration cases, stateids remain valid on the destination while the source clientid4 becomes invalid.

The nfs_client_id4 structure uniquely identifies a specific client boot instance. It contains a verifier4 field (boot instance identifier used to detect client reboots) and an opaque id field (variable-length, up to NFS4_OPAQUE_LIMIT bytes) that uniquely identifies the client across reboots. The server uses this structure to manage leases and detect when a client has rebooted.

Trunking determination for clients using the uniform client ID string approach: when two server IP addresses return the same clientid4, the client performs a cross-confirmation test — doing SETCLIENTID to each candidate lead IP to obtain a new setclientid_confirm verifier (SCn), then sending SETCLIENTID_CONFIRM with each SCn to the new IP address (X). A successful confirmation proves trunking; no success means X is a distinct server. The procedure must be serialized per clientid4 value to prevent races.

The inter-server state transfer that occurs during transparent state migration is a security-sensitive operation. The communication channel used for this transfer must provide adequate authentication and integrity protection to prevent an attacker from injecting or modifying migrated locking state, which could result in unauthorized access or denial of service to legitimate clients.

security