Network File System (NFS) Version 4 Minor Version 2 Protocol
updated by
- rfc-8178 — Rules for NFSv4 Extensions and Minor Versions
Extracted elements (31)
Delegated credentials were rejected for inter-server copy authorization because the destination would authenticate as the user principal and could access other files. RPCSEC_GSSv3 structured privilege assertions are used instead, constraining the destination server's authorization to the specific file being copied.
Discriminated unions are used as operation parameters in NFSv4.2 so that new variants can be added in future minor versions without introducing entirely new operations (e.g., READ2). NFS4ERR_UNION_NOTSUPP enables graceful negotiation when a specific arm is unsupported.
READ_PLUS is introduced as a separate operation rather than extending READ because existing READ clients cannot accept a response containing compact hole metadata. Clients that support READ_PLUS should always prefer it over READ when the server also supports it, as it performs no worse and can dramatically reduce data transfer for sparse files.
The inter-server copy specification deliberately does not mandate the server-to-server copy protocol, allowing homogeneous environments to use optimized mechanisms (block-level replication, shared SAN without data transfer) while still specifying how NFSv4.x can be used when servers are willing.
NFSv4.2 is a superset of NFSv4.1 with all new features optional. An NFSv4.2 metadata server can hand out pNFS file layouts to NFSv4.1 storage devices; stateids returned by NFSv4.2 COMPOUNDs may be used in NFSv4.1 COMPOUNDs directed to data servers.
A copy offload stateid's seqid MUST NOT be zero. Using seqid zero to mean 'most recent' is inappropriate when multiple asynchronous COPY operations may be in progress on the same file in parallel.
If a server supports the CLONE feature, it MUST support the CLONE operation and the clone_blksize attribute on any file system on which CLONE is supported as either source or destination.
If a server supports the intra-server COPY feature and its COPY operation returns a stateid, the server MUST also support CB_OFFLOAD, OFFLOAD_CANCEL, and OFFLOAD_STATUS. A destination server supporting inter-server COPY with a stateid-returning COPY MUST also support COPY_NOTIFY.
If COPY is used for intra-server or inter-server copy, the client MUST support the CB_OFFLOAD operation. If COPY is used for inter-server copy, the client also needs COPY_NOTIFY.
In a pNFS environment, ALLOCATE and DEALLOCATE are sent to the metadata server, which coordinates changes across storage devices. Both operations MUST either fully succeed or fully fail; partial success across devices is not permitted.
New arms of a discriminated union in NFSv4.2 MUST follow the same minor versioning guidelines as operations — they may not be made REQUIRED. A server reports non-support of a new union arm by returning NFS4ERR_UNION_NOTSUPP.
NFSv4 clients and servers supporting inter-server COPY are REQUIRED to implement RPCSEC_GSSv3 including the copy_to_auth, copy_from_auth, and copy_confirm_auth structured privileges, and to support rejecting COPY_NOTIFY requests that do not use RPCSEC_GSS with privacy.
Servers SHOULD reject COPY_NOTIFY requests that do not use RPCSEC_GSS with privacy to ensure the cnr_stateid in the reply is encrypted. For the same reason, clients SHOULD send COPY requests to the destination using RPCSEC_GSS with privacy.
The client SHOULD write cached data back to the source server before an inter-server copy; if it does not, the destination may receive a corrupt copy of the file.
The RPCSEC_GSS3_CREATE control messages for copy_from_auth and copy_to_auth MUST use a Quality of Protection (QoP) of rpc_gss_svc_privacy to protect the shared secret transmitted in those structures.
Under normal operation, the client MUST destroy the copy_from_auth and copy_to_auth RPCSEC_GSSv3 handles once a synchronous inter-server COPY completes or once CB_OFFLOAD reports the result of an asynchronous copy.
When using NFSv4.x as the server-to-server copy protocol, ca_src_stateid in the COPY request MUST be the cnr_stateid returned from the source server via COPY_NOTIFY.
NFSv4.2 introduces 13 new operations: ALLOCATE (59), COPY (60), COPY_NOTIFY (61), DEALLOCATE (62), IO_ADVISE (63), LAYOUTERROR (64), LAYOUTSTATS (65), OFFLOAD_CANCEL (66), OFFLOAD_STATUS (67), READ_PLUS (68), SEEK (69), WRITE_SAME (70), and CLONE (71), plus callback operation CB_OFFLOAD (15).
The netloc4 discriminated union represents network locations using netloc_type4: NL4_NAME (1) carries a UTF-8 hostname string, NL4_URL (2) carries a UTF-8 server URL, and NL4_NETADDR (3) carries a netaddr4 structure as defined in RFC 5661 Section 3.3.9.
The NFS4ERR_UNION_NOTSUPP error code allows a server to signal that an operation is supported but the specific arm of a discriminated union in the request is not, enabling gradual adoption of new union arms without replacing entire operations.
The sec_label file attribute stores Mandatory Access Control (MAC) security labels on files. Its format accommodates any MAC security system. Labeled NFS clients retrieve it to enforce data access control locally or in cooperation with the server.
The space_freed file attribute reports the number of bytes that would be freed when a file is deleted, taking block-sharing into consideration. This is distinct from space_used, which may over- or under-count shared blocks.
Three RPCSEC_GSSv3 structured privilege assertions govern inter-server copy: copy_from_auth (user authorizes source to permit destination to copy), copy_to_auth (user authorizes destination to set up the copy), and copy_confirm_auth (destination confirms authorization to source before data transfer begins).
RFC 7862 registers 13 new NFSv4 operations (operation numbers 59-71) and one new callback operation CB_OFFLOAD (number 15) with IANA. New error codes include NFS4ERR_UNION_NOTSUPP, NFS4ERR_PARTNER_NO_AUTH, and Labeled NFS errors.
Inter-server COPY uses RPCSEC_GSSv3 three-party authorization to prevent the destination server from accessing files beyond the one being copied. The copy_from_auth/copy_to_auth/copy_confirm_auth privilege chain ties the destination's read access to a specific source file and user principal, eliminating the need for preconfigured trust between servers.
Labeled NFS defines three MAC Security modes: Full Mode (both client and server enforce MAC labels independently), Limited Server Mode (server enforces labels with limited client participation), and Guest Mode (server stores sec_label; client retrieves it and enforces access control locally).
Without RPCSEC_GSS, inter-server copy over ONC RPC (AUTH_SYS or AUTH_NONE) lacks strong mutual authentication between source and destination. The cnr_stateid provides initial authentication but cannot defend against man-in-the-middle attacks; additional secure transport (e.g., IPsec) is necessary.
An asynchronous copy offload moves through three states: initiated (COPY operation returns a copy offload stateid), in-progress (client may poll via OFFLOAD_STATUS or cancel via OFFLOAD_CANCEL), and completed (server invokes CB_OFFLOAD callback). The stateid is invalidated by server/client restart, OFFLOAD_CANCEL, or client acknowledgment of CB_OFFLOAD.
copy_from_auth_priv contains cfap_shared_secret (secret4), cfap_destination (netloc4), and cfap_username (utf8str_mixed). copy_to_auth_priv mirrors it with ctap_shared_secret, ctap_source (netloc4 array), and ctap_username. copy_confirm_auth_priv carries ccap_shared_secret_mic (variable opaque, a GSS_GetMIC of the shared secret) and ccap_username.
The app_data_block4 structure contains: adb_offset (offset4), adb_block_size (length4), adb_block_count (length4), adb_reloff_blocknum (length4), adb_block_num (count4), adb_reloff_pattern (length4), and adb_pattern (variable-length opaque). Setting adb_reloff_pattern or adb_reloff_blocknum to NFS4_UINT64_MAX indicates the corresponding field is absent in all ADBs.
The netloc4 union is XDR-encoded as a discriminant (netloc_type4 enum, 4 bytes) followed by the selected arm: utf8str_cis nl_name for NL4_NAME, utf8str_cis nl_url for NL4_URL, or netaddr4 nl_addr for NL4_NETADDR. NL4_NAME values MUST be UTF-8.