Rules for NFSv4 Extensions and Minor Versions

A later minor version may transition a corrected REQUIRED feature through several stages: (1) change uncorrected from REQUIRED to OPTIONAL while requiring at least one version be supported; (2) change corrected from OPTIONAL to REQUIRED, making both REQUIRED; (3) change uncorrected from REQUIRED to OPTIONAL while corrected becomes REQUIRED; and ultimately (4) make the uncorrected version mandatory to not implement.

Extension documents may optionally define a new NFSv4 attribute that signals whether a feature is present and supported, as an alternative to probing via error codes. Since it is easy to test attribute support via the supported_attrs attribute, this can simplify client capability discovery when a feature involves multiple protocol elements.

NFSv4 uses XDR extension rather than XDR replacement to implement version changes. In XDR extension, the set of valid messages in the extended definition is a superset of the base, each previously valid message retains the same structure/interpretation, and messages valid only in the extended definition must be recognizable as unknown extensions when decoded with the base definition.

Optional features may now be added as extensions within an existing minor version, and protocol corrections can be proposed and implemented without creating a new minor version. This provides more implementation flexibility while preserving interoperability on protocol upgrade, because a client and server may each choose a subset of available extensions and successfully use a common subset.

This document consolidates and supersedes all prior minor versioning rules, including those in RFC 5661 and RFC 7862. Any conflict between extension rules here and those in minor version specification RFCs is resolved in favor of this document, except that already-published minor version protocols take precedence over versioning rules.

process

When correcting a REQUIRED feature, the uncorrected version remains REQUIRED (servers must support it until a minor version change), while the corrected version is introduced as OPTIONAL. The corrected version should not be described as 'RECOMMENDED' because which version to support depends on client needs, which may be slow to adopt the updated version.

When correcting an OPTIONAL feature with an XDR change, the corrected and uncorrected versions are treated as two independent OPTIONAL features. This allows older unfixed clients/servers, newer fixed clients/servers, and dual-capable implementations to interoperate: each party can determine which version of the feature is supported by the other party and use that version.

A requester tests a responder's knowledge of protocol elements via specific error responses: NFS4ERR_INVAL on GETATTR/SETATTR or flag bit use means the attribute or flag is unknown; NFS4ERR_OP_ILLEGAL or NFS4ERR_BADXDR on an operation means the operation is unknown; NFS4ERR_BADXDR on a switch arm means the switch case is unknown. Any other error (including NOTSUPP/ATTRNOTSUPP/UNION_NOTSUPP) indicates the element is known but unsupported.

Any protocol element required to be known in a given minor version must also be known in all subsequent minor versions, unless a later minor version marks it as mandatory to not implement. Protocol elements defined in an extension to a minor version are not required to be known in that minor version but must be known in the next minor version.

To establish interoperability, a client and server arrive at a common variant: if the client's minor version is lower, the server accepts it and acts as if extensions from later minor versions are unknown; if the server's minor version is lower, the client uses the server's lower minor version. Within the common variant, the client must additionally probe which OPTIONAL elements the server supports.

When a server supports a newer minor version but a client uses an older one, the server must emulate a server with a more limited XDR: unknown operations return NFS4ERR_OP_ILLEGAL (not NFS4ERR_NOTSUPP), unknown attributes return NFS4ERR_INVAL (not NFS4ERR_ATTRNOTSUPP), unknown switch cases return NFS4ERR_BADXDR (not NFS4ERR_UNION_NOTSUPP), and unknown flag bits return NFS4ERR_INVAL.

XDR additions may also be made by defining XDR structures that overlay nominally opaque fields defined to allow incremental extension, such as pNFS mapping types overlaying opaque arrays defined in RFC 5661. These additions may be made outside the formal extension framework as long as they obey the rules established when the opaque elements were first added.

A determination of knowledge or lack of knowledge of a particular protocol element is expected to remain valid as long as the clientid associated with the request remains valid.

Each clientid relationship between a client and server instance must be devoted to a single minor version. If a server detects that a COMPOUND uses an inappropriate minor version for an established clientid, it MUST reject the request with NFS4ERR_BAD_CLIENTID or NFS4ERR_MINOR_VERS_MISMATCH.

Extensions to an existing minor version that add new or extended callback requests can only be made if the server can determine, based on the client's prior actions, that the client is aware of the changes before sending those callbacks. Similarly, extensions that change response structures may only be sent after the server determines the client is aware of the XDR changes.

Server implementations MUST ensure that the set of supported features and protocol elements does not change within the context of a single clientid. This gives clients the assurance that the set of REQUIRED and OPTIONAL features remains stable for the duration of a clientid.

Servers supporting a given minor version MUST, when returning errors for operations valid in an earlier minor version, return the errors allowed for the current operation in the minor version actually being used by the client — not errors from the server's newer XDR definition.

The following feature types are not allowed as extensions to an existing minor version and require creation of a new minor version: features incorporating non-XDR-based changes (field interpretation changes or behavioral changes), features whose XDR changes violate the extension rules, addition of REQUIRED new features, and changes to the status of existing features such as converting them to mandatory to not implement.

A 'feature package' is a set of features defined together, either as part of a minor version or as part of the same protocol extension. If a responder is aware of one protocol element within a feature package, it must be aware of all protocol elements within that feature package.

Allowed XDR extensions within NFSv4 include: addition of new operation codes within COMPOUND/CB_COMPOUND; addition of new attributes with bitmap positions and XDR typedefs; addition of new values to existing enums; addition of previously unassigned bit values to flag words; and addition of new cases to existing switches that lacked a default case. New RPC procedures are never allowed.

NFSv4 defines two special minor version variants per minor version: the 'base minor version' is the variant as originally defined without any post-publication extensions or corrections, and the 'current minor version' includes all Standards Track extensions and corrections published up to a given time. Each implementation implements some variant that is a subset of the current and a superset of the base.

Responders handle received protocol elements in one of three ways: (1) the element is unknown, triggering NFS4ERR_OP_ILLEGAL, NFS4ERR_BADXDR, or NFS4ERR_INVAL; (2) the element is known but unsupported, triggering NFS4ERR_NOTSUPP, NFS4ERR_UNION_NOTSUPP, or NFS4ERR_ATTRNOTSUPP; or (3) the element is known and supported, returning success or a non-special error.

The following XDR changes are prohibited in NFSv4: any structural modification or deletion of existing requests or replies beyond the listed additions; addition of new RPC procedures to the NFSv4 or callback program; and deletion or reuse of existing RPC procedures, operation codes, enum values, flag bits, or switch cases.

Since no substantive protocol changes are proposed in RFC 8178, no security considerations apply. The document solely defines procedural and structural rules for NFSv4 protocol extension and minor version management.

security