Network Working Group B. Callaghan Request for Comments: 1813 B. Pawlowski Category: Informational P. Staubach Sun Microsystems, Inc. June 1995 NFS Version 3 Protocol Specification Status of this Memo This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind. Distribution of this memo is unlimited. IESG Note Internet Engineering Steering Group comment: please note that the IETF is not involved in creating or maintaining this specification. This is the significance of the specification not being on the standards track. Abstract This paper describes the NFS version 3 protocol. This paper is provided so that people can write compatible implementations. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Scope of the NFS version 3 protocol . . . . . . . . . . 4 1.2 Useful terms . . . . . . . . . . . . . . . . . . . . . . 5 1.3 Remote Procedure Call . . . . . . . . . . . . . . . . . 5 1.4 External Data Representation . . . . . . . . . . . . . . 5 1.5 Authentication and Permission Checking . . . . . . . . . 7 1.6 Philosophy . . . . . . . . . . . . . . . . . . . . . . . 8 1.7 Changes from the NFS version 2 protocol . . . . . . . . 11 2. RPC Information . . . . . . . . . . . . . . . . . . . . . 14 2.1 Authentication . . . . . . . . . . . . . . . . . . . . . 14 2.2 Constants . . . . . . . . . . . . . . . . . . . . . . . 14 2.3 Transport address . . . . . . . . . . . . . . . . . . . 14 2.4 Sizes . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.5 Basic Data Types . . . . . . . . . . . . . . . . . . . . 15 2.6 Defined Error Numbers . . . . . . . . . . . . . . . . . 17 3. Server Procedures . . . . . . . . . . . . . . . . . . . . 27 3.1 General comments on attributes . . . . . . . . . . . . . 29 3.2 General comments on filenames . . . . . . . . . . . . . 30 3.3.0 NULL: Do nothing . . . . . . . . . . . . . . . . . . . . 31 Callaghan, el al Informational [Page 1] RFC 1813 NFS Version 3 Protocol June 1995 3.3.1 GETATTR: Get file attributes . . . . . . . . . . . . . . 32 3.3.2 SETATTR: Set file attributes . . . . . . . . . . . . . . 33 3.3.3 LOOKUP: Lookup filename . . . . . . . . . . . . . . . . 37 3.3.4 ACCESS: Check access permission . . . . . . . . . . . . 40 3.3.5 READLINK: Read from symbolic link . . . . . . . . . . . 44 3.3.6 READ: Read from file . . . . . . . . . . . . . . . . . . 46 3.3.7 WRITE: Write to file . . . . . . . . . . . . . . . . . . 49 3.3.8 CREATE: Create a file . . . . . . . . . . . . . . . . . 54 3.3.9 MKDIR: Create a directory . . . . . . . . . . . . . . . 58 3.3.10 SYMLINK: Create a symbolic link . . . . . . . . . . . . 61 3.3.11 MKNOD: Create a special device . . . . . . . . . . . . . 63 3.3.12 REMOVE: Remove a file . . . . . . . . . . . . . . . . . 67 3.3.13 RMDIR: Remove a directory . . . . . . . . . . . . . . . 69 3.3.14 RENAME: Rename a file or directory . . . . . . . . . . . 71 3.3.15 LINK: Create link to an object . . . . . . . . . . . . . 74 3.3.16 READDIR: Read From directory . . . . . . . . . . . . . . 76 3.3.17 READDIRPLUS: Extended read from directory . . . . . . . 80 3.3.18 FSSTAT: Get dynamic file system information . . . . . . 84 3.3.19 FSINFO: Get static file system information . . . . . . . 86 3.3.20 PATHCONF: Retrieve POSIX information . . . . . . . . . . 90 3.3.21 COMMIT: Commit cached data on a server to stable storage 92 4. Implementation issues . . . . . . . . . . . . . . . . . . 96 4.1 Multiple version support . . . . . . . . . . . . . . . . 96 4.2 Server/client relationship . . . . . . . . . . . . . . . 96 4.3 Path name interpretation . . . . . . . . . . . . . . . . 97 4.4 Permission issues . . . . . . . . . . . . . . . . . . . 98 4.5 Duplicate request cache . . . . . . . . . . . . . . . . 99 4.6 File name component handling . . . . . . . . . . . . . . 101 4.7 Synchronous modifying operations . . . . . . . . . . . . 101 4.8 Stable storage . . . . . . . . . . . . . . . . . . . . . 101 4.9 Lookups and name resolution . . . . . . . . . . . . . . 102 4.10 Adaptive retransmission . . . . . . . . . . . . . . . . 102 4.11 Caching policies . . . . . . . . . . . . . . . . . . . . 102 4.12 Stable versus unstable writes. . . . . . . . . . . . . . 103 4.13 32 bit clients/servers and 64 bit clients/servers. . . . 104 5. Appendix I: Mount protocol . . . . . . . . . . . . . . . . 106 5.1 RPC Information . . . . . . . . . . . . . . . . . . . . 106 5.1.1 Authentication . . . . . . . . . . . . . . . . . . . . 106 5.1.2 Constants . . . . . . . . . . . . . . . . . . . . . . 106 5.1.3 Transport address . . . . . . . . . . . . . . . . . . 106 5.1.4 Sizes . . . . . . . . . . . . . . . . . . . . . . . . 106 5.1.5 Basic Data Types . . . . . . . . . . . . . . . . . . . 106 5.2 Server Procedures . . . . . . . . . . . . . . . . . . . 107 5.2.0 NULL: Do nothing . . . . . . . . . . . . . . . . . . . 108 5.2.1 MNT: Add mount entry . . . . . . . . . . . . . . . . . 109 5.2.2 DUMP: Return mount entries . . . . . . . . . . . . . . 110 5.2.3 UMNT: Remove mount entry . . . . . . . . . . . . . . . 111 5.2.4 UMNTALL: Remove all mount entries . . . . . . . . . . 112 Callaghan, el al Informational [Page 2] RFC 1813 NFS Version 3 Protocol June 1995 5.2.5 EXPORT: Return export list . . . . . . . . . . . . . . 113 6. Appendix II: Lock manager protocol . . . . . . . . . . . . 114 6.1 RPC Information . . . . . . . . . . . . . . . . . . . . 114 6.1.1 Authentication . . . . . . . . . . . . . . . . . . . . 114 6.1.2 Constants . . . . . . . . . . . . . . . . . . . . . . 114 6.1.3 Transport Address . . . . . . . . . . . . . . . . . . 115 6.1.4 Basic Data Types . . . . . . . . . . . . . . . . . . . 115 6.2 NLM Procedures . . . . . . . . . . . . . . . . . . . . . 118 6.2.0 NULL: Do nothing . . . . . . . . . . . . . . . . . . . 120 6.3 Implementation issues . . . . . . . . . . . . . . . . . 120 6.3.1 64-bit offsets and lengths . . . . . . . . . . . . . . 120 6.3.2 File handles . . . . . . . . . . . . . . . . . . . . . 120 7. Appendix III: Bibliography . . . . . . . . . . . . . . . . 122 8. Security Considerations . . . . . . . . . . . . . . . . . 125 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 125 10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . 126 1. Introduction Sun's NFS protocol provides transparent remote access to shared file systems across networks. The NFS protocol is designed to be machine, operating system, network architecture, and transport protocol independent. This independence is achieved through the use of Remote Procedure Call (RPC) primitives built on top of an eXternal Data Representation (XDR). Implementations of the NFS version 2 protocol exist for a variety of machines, from personal computers to supercomputers. The initial version of the NFS protocol is specified in the Network File System Protocol Specification [RFC1094]. A description of the initial implementation can be found in [Sandberg]. The supporting MOUNT protocol performs the operating system-specific functions that allow clients to attach remote directory trees to a point within the local file system. The mount process also allows the server to grant remote access privileges to a restricted set of clients via export control. The Lock Manager provides support for file locking when used in the NFS environment. The Network Lock Manager (NLM) protocol isolates the inherently stateful aspects of file locking into a separate protocol. A complete description of the above protocols and their implementation is to be found in [X/OpenNFS]. The purpose of this document is to: Callaghan, el al Informational [Page 3] RFC 1813 NFS Version 3 Protocol June 1995 o Specify the NFS version 3 protocol. o Describe semantics of the protocol through annotation and description of intended implementation. o Specify the MOUNT version 3 protocol. o Briefly describe the changes between the NLM version 3 protocol and the NLM version 4 protocol. The normative text is the description of the RPC procedures and arguments and results, which defines the over-the-wire protocol, and the semantics of those procedures. The material describing implementation practice aids the understanding of the protocol specification and describes some possible implementation issues and solutions. It is not possible to describe all implementations and the UNIX operating system implementation of the NFS version 3 protocol is most often used to provide examples. Given that, the implementation discussion does not bear the authority of the description of the over-the-wire protocol itself. 1.1 Scope of the NFS version 3 protocol This revision of the NFS protocol addresses new requirements. The need to support larger files and file systems has prompted extensions to allow 64 bit file sizes and offsets. The revision enhances security by adding support for an access check to be done on the server. Performance modifications are of three types: 1. The number of over-the-wire packets for a given set of file operations is reduced by returning file attributes on every operation, thus decreasing the number of calls to get modified attributes. 2. The write throughput bottleneck caused by the synchronous definition of write in the NFS version 2 protocol has been addressed by adding support so that the NFS server can do unsafe writes. Unsafe writes are writes which have not been committed to stable storage before the operation returns. This specification defines a method for committing these unsafe writes to stable storage in a reliable way. 3. Limitations on transfer sizes have been relaxed. The ability to support multiple versions of a protocol in RPC will allow implementors of the NFS version 3 protocol to define Callaghan, el al Informational [Page 4] RFC 1813 NFS Version 3 Protocol June 1995 clients and servers that provide backwards compatibility with the existing installed base of NFS version 2 protocol implementations. The extensions described here represent an evolution of the existing NFS protocol and most of the design features of the NFS protocol described in [Sandberg] persist. See Changes from the NFS version 2 protocol on page 11 for a more detailed summary of the changes introduced by this revision. 1.2 Useful terms In this specification, a "server" is a machine that provides resources to the network; a "client" is a machine that accesses resources over the network; a "user" is a person logged in on a client; an "application" is a program that executes on a client. 1.3 Remote Procedure Call The Sun Remote Procedure Call specification provides a procedure-oriented interface to remote services. Each server supplies a program, which is a set of procedures. The NFS service is one such program. The combination of host address, program number, version number, and procedure number specify one remote service procedure. Servers can support multiple versions of a program by using different protocol version numbers. The NFS protocol was designed to not require any specific level of reliability from its lower levels so it could potentially be used on many underlying transport protocols. The NFS service is based on RPC which provides the abstraction above lower level network and transport protocols. The rest of this document assumes the NFS environment is implemented on top of Sun RPC, which is specified in [RFC1057]. A complete discussion is found in [Corbin]. 1.4 External Data Representation The eXternal Data Representation (XDR) specification provides a standard way of representing a set of data types on a network. This solves the problem of different byte orders, structure alignment, and data type representation on different, communicating machines. In this document, the RPC Data Description Language is used to specify the XDR format parameters and results to each of the RPC service procedures that an NFS server provides. The RPC Data Callaghan, el al Informational [Page 5] RFC 1813 NFS Version 3 Protocol June 1995 Description Language is similar to declarations in the C programming language. A few new constructs have been added. The notation: string name[SIZE]; string data; defines name, which is a fixed size block of SIZE bytes, and data, which is a variable sized block of up to DSIZE bytes. This notation indicates fixed-length arrays and arrays with a variable number of elements up to a fixed maximum. A variable-length definition with no size specified means there is no maximum size for the field. The discriminated union definition: union example switch (enum status) { case OK: struct { filename file1; filename file2; integer count; } case ERROR: struct { errstat error; integer errno; } default: void; } defines a structure where the first thing over the network is an enumeration type called status. If the value of status is OK, the next thing on the network will be the structure containing file1, file2, and count. Else, if the value of status is ERROR, the next thing on the network will be a structure containing error and errno. If the value of status is neither OK nor ERROR, then there is no more data in the structure. The XDR type, hyper, is an 8 byte (64 bit) quantity. It is used in the same way as the integer type. For example: hyper foo; unsigned hyper bar; foo is an 8 byte signed value, while bar is an 8 byte unsigned value. Callaghan, el al Informational [Page 6] RFC 1813 NFS Version 3 Protocol June 1995 Although RPC/XDR compilers exist to generate client and server stubs from RPC Data Description Language input, NFS implementations do not require their use. Any software that provides equivalent encoding and decoding to the canonical network order of data defined by XDR can be used to interoperate with other NFS implementations. XDR is described in [RFC1014]. 1.5 Authentication and Permission Checking The RPC protocol includes a slot for authentication parameters on every call. The contents of the authentication parameters are determined by the type of authentication used by the server and client. A server may support several different flavors of authentication at once. The AUTH_NONE flavor provides null authentication, that is, no authentication information is passed. The AUTH_UNIX flavor provides UNIX-style user ID, group ID, and groups with each call. The AUTH_DES flavor provides DES-