RFC2119], except where "REQUIRED" and "RECOMMENDED" are used as qualifiers to distinguish classes of attributes as described in Sections 22.214.171.124 and 5 of this document. RFC1094] and 3 [RFC1813]. It retains the essential characteristics of previous versions: design for easy recovery; independent of transport protocols, operating systems, and file systems; simplicity; and good performance. The NFSv4 revision has the following goals: o Improved access and good performance on the Internet. The protocol is designed to transit firewalls easily, perform well where latency is high and bandwidth is low, and scale to very large numbers of clients per server. o Strong security with negotiation built into the protocol. The protocol builds on the work of the Open Network Computing (ONC) Remote Procedure Call (RPC) working group in supporting the RPCSEC_GSS protocol (see both [RFC2203] and [RFC5403]). Additionally, the NFSv4 protocol provides a mechanism to allow clients and servers the ability to negotiate security and require clients and servers to support a minimal set of security schemes. o Good cross-platform interoperability. The protocol features a file system model that provides a useful, common set of features that does not unduly favor one file system or operating system over another. o Designed for protocol extensions. The protocol is designed to accept standard extensions that do not compromise backward compatibility.
This document, together with the companion External Data Representation (XDR) description document [RFC7531], obsoletes [RFC3530] as the authoritative document describing NFSv4. It does not introduce any over-the-wire protocol changes, in the sense that previously valid requests remain valid. RFC7531] contains the definitions in XDR description language of the constructs used by the protocol. Inside this document, several of the constructs are reproduced for purposes of explanation. The reader is warned of the possibility of errors in the reproduced constructs outside of [RFC7531]. For any part of the document that is inconsistent with [RFC7531], [RFC7531] is to be considered authoritative. RFC4506] and [RFC5531]. A basic knowledge of file systems and distributed file systems is expected as well. RFC4506] and [RFC5531]. To meet end-to-end security requirements, the RPCSEC_GSS framework (both version 1 in [RFC2203] and version 2 in [RFC5403]) will be used to extend the basic RPC security. With the use of RPCSEC_GSS, various mechanisms can be provided to offer authentication, integrity, and privacy to the NFSv4 protocol. Kerberos V5 will be used as described in [RFC4121] to provide one security framework. With the use of RPCSEC_GSS, other mechanisms may also be specified and used for NFSv4 security. To enable in-band security negotiation, the NFSv4 protocol has added a new operation that provides the client with a method of querying the server about its policies regarding which security mechanisms must be used for access to the server's file system resources. With this, the client can securely match the security mechanism that meets the policies specified at both the client and server.
Section 5). Several (but not all) of the REQUIRED attributes are derived from the attributes of NFSv3 (see the definition of the fattr3 data type in [RFC1813]). An example of a REQUIRED attribute is the file object's type (Section 126.96.36.199) so that regular files can be distinguished from directories (also known as folders in some operating environments) and other types of objects. REQUIRED attributes are discussed in Section 5.1. An example of the RECOMMENDED attributes is an acl (Section 6.2.1). This attribute defines an Access Control List (ACL) on a file object. An ACL provides file access control beyond the model used in NFSv3. The ACL definition allows for specification of specific sets of permissions for individual users and groups. In addition, ACL inheritance allows propagation of access permissions and restriction down a directory tree as file system objects are created. RECOMMENDED attributes are discussed in Section 5.2. A named attribute is an opaque byte stream that is associated with a directory or file and referred to by a string name. Named attributes are meant to be used by client applications as a method to associate application-specific data with a regular file or directory. NFSv4.1 modifies named attributes relative to NFSv4.0 by tightening the allowed operations in order to prevent the development of non-interoperable implementations. Named attributes are discussed in Section 5.3.
Section 9.9) can be combined. The CLOSE operation also provides for the release of state accumulated by OPEN. RFC1813]. The state associated with file locks is maintained at the server under a lease-based model. The server defines a single lease period for all state held by an NFS client.
If the client does not renew its lease within the defined period, all state associated with the client's lease may be released by the server. The client may renew its lease by use of the RENEW operation or implicitly by use of other operations (primarily READ). Section 10.4). If the client is granted an OPEN_DELEGATE_READ delegation, it is assured that no other client has the ability to write to the file for the duration of the delegation. If the client is granted an OPEN_DELEGATE_WRITE delegation, the client is assured that no other client has read or write access to the file. Delegations can be recalled by the server. If another client requests access to the file in such a way that the access conflicts with the granted delegation, the server is able to notify the initial client and recall the delegation. This requires that a callback path exist between the server and client. If this callback path does not exist, then delegations cannot be granted. The essence of a delegation is that it allows the client to locally service operations such as OPEN, CLOSE, LOCK, LOCKU, READ, or WRITE without immediate interaction with the server.
Section 188.8.131.52. Byte: In this document, a byte is an octet, i.e., a datum exactly 8 bits in length. Client: The client is the entity that accesses the NFS server's resources. The client may be an application that contains the logic to access the NFS server directly. The client may also be the traditional operating system client that provides remote file system services for a set of applications. With reference to byte-range locking, the client is also the entity that maintains a set of locks on behalf of one or more applications. This client is responsible for crash or failure recovery for those locks it manages. Note that multiple clients may share the same transport and connection, and multiple clients may exist on the same network node. Client ID: The client ID is a 64-bit quantity used as a unique, shorthand reference to a client-supplied verifier and ID. The server is responsible for supplying the client ID. File System: The file system is the collection of objects on a server that share the same fsid attribute (see Section 184.108.40.206). Lease: A lease is an interval of time defined by the server for which the client is irrevocably granted a lock. At the end of a lease period the lock may be revoked if the lease has not been extended. The lock must be revoked if a conflicting lock has been granted after the lease interval. All leases granted by a server have the same fixed duration. Note that the fixed interval duration was chosen to alleviate the expense a server would have in maintaining state about variable- length leases across server failures.
Lock: The term "lock" is used to refer to record (byte-range) locks as well as share reservations unless specifically stated otherwise. Lock-Owner: Each byte-range lock is associated with a specific lock-owner and an open-owner. The lock-owner consists of a client ID and an opaque owner string. The client presents this to the server to establish the ownership of the byte-range lock as needed. Open-Owner: Each open file is associated with a specific open-owner, which consists of a client ID and an opaque owner string. The client presents this to the server to establish the ownership of the open as needed. READ Bypass Stateid: The READ Bypass Stateid is a special locking object and is defined in Section 220.127.116.11. Server: The "server" is the entity responsible for coordinating client access to a set of file systems. Stable Storage: NFSv4 servers must be able to recover without data loss from multiple power failures (including cascading power failures, that is, several power failures in quick succession), operating system failures, and hardware failure of components other than the storage medium itself (for example, disk, non-volatile RAM). Some examples of stable storage that are allowable for an NFS server include: (1) Media commit of data. That is, the modified data has been successfully written to the disk media -- for example, the disk platter. (2) An immediate reply disk drive with battery-backed on-drive intermediate storage or uninterruptible power system (UPS). (3) Server commit of data with battery-backed intermediate storage and recovery software. (4) Cache commit with UPS and recovery software.
Stateid: A stateid is a 128-bit quantity returned by a server that uniquely identifies the open and locking states provided by the server for a specific open-owner or lock-owner/open-owner pair for a specific file and type of lock. Verifier: A verifier is a 64-bit quantity generated by the client that the server can use to determine if the client has restarted and lost all previous lock state. RFC3530] are: o The XDR definition has been moved to a companion document [RFC7531]. o The IETF intellectual property statements were updated to the latest version. o There is a restructured and more complete explanation of multi- server namespace features. o The handling of domain names was updated to reflect Internationalized Domain Names in Applications (IDNA) [RFC5891]. o The previously required LIPKEY and SPKM-3 security mechanisms have been removed. o Some clarification was provided regarding a client re-establishing callback information to the new server if state has been migrated. o A third edge case was added for courtesy locks and network partitions. o The definition of stateid was strengthened. RFC3530] replaced and obsoleted the definition present in [RFC3010]. While portions of the two documents remained the same, there were substantive changes in others. The changes made between [RFC3010] and [RFC3530] reflect implementation experience and further review of the protocol.
The following list is not inclusive of all changes but presents some of the most notable changes or additions made: o The state model has added an open_owner4 identifier. This was done to accommodate POSIX-based clients and the model they use for file locking. For POSIX clients, an open_owner4 would correspond to a file descriptor potentially shared amongst a set of processes and the lock_owner4 identifier would correspond to a process that is locking a file. o Added clarifications and error conditions for the handling of the owner and group attributes. Since these attributes are string based (as opposed to the numeric uid/gid of previous versions of NFS), translations may not be available and hence the changes made. o Added clarifications for the ACL and mode attributes to address evaluation and partial support. o For identifiers that are defined as XDR opaque, set limits on their size. o Added the mounted_on_fileid attribute to allow POSIX clients to correctly construct local mounts. o Modified the SETCLIENTID/SETCLIENTID_CONFIRM operations to deal correctly with confirmation details along with adding the ability to specify new client callback information. Also added clarification of the callback information itself. o Added a new operation RELEASE_LOCKOWNER to enable notifying the server that a lock_owner4 will no longer be used by the client. o Added RENEW operation changes to identify the client correctly and allow for additional error returns. o Verified error return possibilities for all operations. o Removed use of the pathname4 data type from LOOKUP and OPEN in favor of having the client construct a sequence of LOOKUP operations to achieve the same effect.
RFC4506] and RPC [RFC5531] documents. The next sections build upon the XDR data types to define types and structures specific to this protocol. As a reminder, the size constants and authoritative definitions can be found in [RFC7531]. Table 1 lists the base NFSv4 data types. +-----------------+-------------------------------------------------+ | Data Type | Definition | +-----------------+-------------------------------------------------+ | int32_t | typedef int int32_t; | | | | | uint32_t | typedef unsigned int uint32_t; | | | | | int64_t | typedef hyper int64_t; | | | | | uint64_t | typedef unsigned hyper uint64_t; | | | | | attrlist4 | typedef opaque attrlist4<>; | | | | | | Used for file/directory attributes. | | | | | bitmap4 | typedef uint32_t bitmap4<>; | | | | | | Used in attribute array encoding. | | | | | changeid4 | typedef uint64_t changeid4; | | | | | | Used in the definition of change_info4. | | | | | clientid4 | typedef uint64_t clientid4; | | | | | | Shorthand reference to client identification. | | | | | count4 | typedef uint32_t count4; | | | | | | Various count parameters (READ, WRITE, COMMIT). | | | | | length4 | typedef uint64_t length4; | | | | | | Describes LOCK lengths. | | | |
| mode4 | typedef uint32_t mode4; | | | | | | Mode attribute data type. | | | | | nfs_cookie4 | typedef uint64_t nfs_cookie4; | | | | | | Opaque cookie value for READDIR. | | | | | nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; | | | | | | Filehandle definition. | | | | | nfs_ftype4 | enum nfs_ftype4; | | | | | | Various defined file types. | | | | | nfsstat4 | enum nfsstat4; | | | | | | Return value for operations. | | | | | nfs_lease4 | typedef uint32_t nfs_lease4; | | | | | | Duration of a lease in seconds. | | | | | offset4 | typedef uint64_t offset4; | | | | | | Various offset designations (READ, WRITE, LOCK, | | | COMMIT). | | | | | qop4 | typedef uint32_t qop4; | | | | | | Quality of protection designation in SECINFO. | | | | | sec_oid4 | typedef opaque sec_oid4<>; | | | | | | Security Object Identifier. The sec_oid4 data | | | type is not really opaque. Instead, it | | | contains an ASN.1 OBJECT IDENTIFIER as used by | | | GSS-API in the mech_type argument to | | | GSS_Init_sec_context. See [RFC2743] for | | | details. | | | | | seqid4 | typedef uint32_t seqid4; | | | | | | Sequence identifier used for file locking. | | | |
| utf8string | typedef opaque utf8string<>; | | | | | | UTF-8 encoding for strings. | | | | | utf8str_cis | typedef utf8string utf8str_cis; | | | | | | Case-insensitive UTF-8 string. | | | | | utf8str_cs | typedef utf8string utf8str_cs; | | | | | | Case-sensitive UTF-8 string. | | | | | utf8str_mixed | typedef utf8string utf8str_mixed; | | | | | | UTF-8 strings with a case-sensitive prefix and | | | a case-insensitive suffix. | | | | | component4 | typedef utf8str_cs component4; | | | | | | Represents pathname components. | | | | | linktext4 | typedef opaque linktext4<>; | | | | | | Symbolic link contents ("symbolic link" is | | | defined in an Open Group [openg_symlink] | | | standard). | | | | | ascii_REQUIRED4 | typedef utf8string ascii_REQUIRED4; | | | | | | String is sent as ASCII and thus is | | | automatically UTF-8. | | | | | pathname4 | typedef component4 pathname4<>; | | | | | | Represents pathname for fs_locations. | | | | | nfs_lockid4 | typedef uint64_t nfs_lockid4; | | | | | verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | | | | | | Verifier used for various operations (COMMIT, | | | CREATE, OPEN, READDIR, WRITE) | | | NFS4_VERIFIER_SIZE is defined as 8. | +-----------------+-------------------------------------------------+ Table 1: Base NFSv4 Data Types
The bitmap is a counted array of 32-bit integers used to contain bit values. The position of the integer in the array that contains bit n can be computed from the expression (n / 32), and its bit within that integer is (n mod 32). 0 1 +-----------+-----------+-----------+-- | count | 31 .. 0 | 63 .. 32 | +-----------+-----------+-----------+-- RFC 1833 */ string r_netid<>; /* network id */ string r_addr<>; /* universal address */ }; The clientaddr4 structure is used as part of the SETCLIENTID operation, either (1) to specify the address of the client that is using a client ID or (2) as part of the callback registration. The r_netid and r_addr fields respectively contain a network id and universal address. The network id and universal address concepts, together with formats for TCP over IPv4 and TCP over IPv6, are defined in [RFC5665], specifically Tables 2 and 3 and Sections 18.104.22.168 and 22.214.171.124.
RFC5531] and [RFC4506]. The RPCSEC_GSS security flavors as defined in version 1 ([RFC2203]) and version 2 ([RFC5403]) MUST be implemented as the mechanism to deliver stronger security for the NFSv4 protocol. However, deployment of RPCSEC_GSS is optional. RFC3232] for the NFS protocol SHOULD be the default configuration. Using the registered port for NFS services means the NFS client will not need to use the RPC binding protocols as described in [RFC1833]; this will allow NFS to transit firewalls. Where an NFSv4 implementation supports operation over the IP network protocol, the supported transport layer between NFS and IP MUST be an IETF standardized transport protocol that is specified to avoid network congestion; such transports include TCP and the Stream Control Transmission Protocol (SCTP). To enhance the possibilities for interoperability, an NFSv4 implementation MUST support operation over the TCP transport protocol. If TCP is used as the transport, the client and server SHOULD use persistent connections. This will prevent the weakening of TCP's congestion control via short-lived connections and will improve performance for the Wide Area Network (WAN) environment by eliminating the need for SYN handshakes. As noted in Section 19, the authentication model for NFSv4 has moved from machine-based to principal-based. However, this modification of the authentication model does not imply a technical requirement to
move the TCP connection management model from whole machine-based to one based on a per-user model. In particular, NFS over TCP client implementations have traditionally multiplexed traffic for multiple users over a common TCP connection between an NFS client and server. This has been true, regardless of whether the NFS client is using AUTH_SYS, AUTH_DH, RPCSEC_GSS, or any other flavor. Similarly, NFS over TCP server implementations have assumed such a model and thus scale the implementation of TCP connection management in proportion to the number of expected client machines. It is intended that NFSv4 will not modify this connection management model. NFSv4 clients that violate this assumption can expect scaling issues on the server and hence reduced service.
RFC2203], an additional security flavor of RPCSEC_GSS has been introduced, which uses the functionality of GSS-API [RFC2743]. This allows for the use of various security mechanisms by the RPC layer without the additional implementation overhead of adding RPC security flavors. For NFSv4, the RPCSEC_GSS security flavor MUST be used to enable the mandatory-to-implement security mechanism. Other flavors, such as AUTH_NONE, AUTH_SYS, and AUTH_DH, MAY be implemented as well. RFC4121] MUST be implemented with the RPCSEC_GSS services as specified in Table 2. Both client and server MUST support each of the pseudo-flavors. +--------+-------+----------------------+-----------------------+ | Number | Name | Mechanism's OID | RPCSEC_GSS service | +--------+-------+----------------------+-----------------------+ | 390003 | krb5 | 1.2.840.1135126.96.36.199 | rpc_gss_svc_none | | 390004 | krb5i | 1.2.840.1135188.8.131.52 | rpc_gss_svc_integrity | | 390005 | krb5p | 1.2.840.1135184.108.40.206 | rpc_gss_svc_privacy | +--------+-------+----------------------+-----------------------+ Table 2: Mapping Pseudo-Flavor to Service Note that the pseudo-flavor is presented here as a mapping aid to the implementer. Because this NFS protocol includes a method to negotiate security and it understands the GSS-API mechanism, the
pseudo-flavor is not needed. The pseudo-flavor is needed for NFSv3 since the security negotiation is done via the MOUNT protocol as described in [RFC2623]. At the time this document was specified, the Advanced Encryption Standard (AES) with HMAC-SHA1 was a required algorithm set for Kerberos V5. In contrast, when NFSv4.0 was first specified in [RFC3530], weaker algorithm sets were REQUIRED for Kerberos V5, and were REQUIRED in the NFSv4.0 specification, because the Kerberos V5 specification at the time did not specify stronger algorithms. The NFSv4 specification does not specify required algorithms for Kerberos V5, and instead, the implementer is expected to track the evolution of the Kerberos V5 standard if and when stronger algorithms are specified. RFC6649] as to why weak algorithms should be disabled by default. Section 19 for further discussion.
RFC2743] and Section 16.31.4) is to be used for server access. In general, the client will not have to use the SECINFO operation, except during initial communication with the server or when the client encounters a new security policy as the client navigates the namespace. Either condition will force the client to negotiate a new security triple. Section 16.31 for further discussion of how the client will respond to the NFS4ERR_WRONGSEC error and use SECINFO.
Regardless of what security mechanism under RPCSEC_GSS is being used, the NFS server MUST identify itself in GSS-API via a GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE names are of the form: service@hostname For NFS, the "service" element is: nfs Implementations of security mechanisms will convert nfs@hostname to various different forms. For Kerberos V5, the following form is RECOMMENDED: nfs/hostname For Kerberos V5, nfs/hostname would be a server principal in the Kerberos Key Distribution Center database. This is the same principal the client acquired a GSS-API context for when it issued the SETCLIENTID operation; therefore, the realm name for the server principal must be the same for the callback as it was for the SETCLIENTID.