NNeettwwoorrkk FFiillee SSyysstteemm:: VVeerrssiioonn 22 PPrroottooccooll SSppeecciiffiiccaattiioonn 11.. SSttaattuuss ooff tthhiiss SSttaannddaarrdd Note: This document specifies a protocol that Sun Microsys- tems, Inc., and others are using. It specifies it in stan- dard ARPA RFC form. 22.. IInnttrroodduuccttiioonn The Sun Network Filesystem (NFS) protocol provides transpar- ent remote access to shared filesystems over local area net- works. The NFS protocol is designed to be machine, operat- ing 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 exist for a variety of machines, from personal computers to super- computers. The supporting mount protocol allows the server to hand out remote access privileges to a restricted set of clients. It performs the operating system-specific functions that allow, for example, to attach remote directory trees to some local file system. 22..11.. RReemmoottee PPrroocceedduurree CCaallll Sun's remote procedure call specification provides a proce- dure- oriented interface to remote services. Each server supplies a program that is a set of procedures. NFS is one such "program". The combination of host address, program number, and procedure number specifies one remote service procedure. RPC does not depend on services provided by spe- cific protocols, so it can be used with any underlying transport protocol. See the _R_e_m_o_t_e _P_r_o_c_e_d_u_r_e _C_a_l_l_s_: _P_r_o_t_o_- _c_o_l _S_p_e_c_i_f_i_c_a_t_i_o_n chapter of this manual. 22..22.. EExxtteerrnnaall DDaattaa RReepprreesseennttaattiioonn The External Data Representation (XDR) standard provides a common way of representing a set of data types over a net- work. The NFS Protocol Specification is written using the RPC data description language. For more information, see the _E_x_t_e_r_n_a_l _D_a_t_a _R_e_p_r_e_s_e_n_t_a_t_i_o_n _S_t_a_n_d_a_r_d_: _P_r_o_t_o_c_o_l _S_p_e_c_i_- _f_i_c_a_t_i_o_n_. Sun provides implementations of XDR and RPC, but NFS does not require their use. Any software that provides equivalent functionality can be used, and if the encoding is exactly the same it can interoperate with other implementa- tions of NFS. - 1 - Page 2 Network File System: Version 2 Protocol Specification 22..33.. SSttaatteelleessss SSeerrvveerrss The NFS protocol is stateless. That is, a server does not need to maintain any extra state information about any of its clients in order to function correctly. Stateless servers have a distinct advantage over stateful servers in the event of a failure. With stateless servers, a client need only retry a request until the server responds; it does not even need to know that the server has crashed, or the network temporarily went down. The client of a stateful server, on the other hand, needs to either detect a server crash and rebuild the server's state when it comes back up, or cause client operations to fail. This may not sound like an important issue, but it affects the protocol in some unexpected ways. We feel that it is worth a bit of extra complexity in the protocol to be able to write very simple servers that do not require fancy crash recovery. On the other hand, NFS deals with objects such as files and directories that inherently have state -- what good would a file be if it did not keep its contents intact? The goal is to not introduce any extra state in the protocol itself. Another way to simplify recovery is by making operations "idempotent" whenever possible (so that they can potentially be repeated). 33.. NNFFSS PPrroottooccooll DDeeffiinniittiioonn Servers have been known to change over time, and so can the protocol that they use. So RPC provides a version number with each RPC request. This RFC describes version two of the NFS protocol. Even in the second version, there are various obsolete procedures and parameters, which will be removed in later versions. An RFC for version three of the NFS protocol is currently under preparation. 33..11.. FFiillee SSyysstteemm MMooddeell NFS assumes a file system that is hierarchical, with direc- tories as all but the bottom-level files. Each entry in a directory (file, directory, device, etc.) has a string name. Different operating systems may have restrictions on the depth of the tree or the names used, as well as using different syntax to represent the "pathname", which is the concatenation of all the "components" (directory and file names) in the name. A "file system" is a tree on a single server (usually a single disk or physical partition) with a specified "root". Some operating systems provide a "mount" operation to make all file systems appear as a single tree, while others maintain a "forest" of file systems. Files are unstructured streams of uninterpreted bytes. Version 3 of NFS uses a slightly more general file system model. Network File System: Version 2 Protocol Specification Page 3 NFS looks up one component of a pathname at a time. It may not be obvious why it does not just take the whole pathname, traipse down the directories, and return a file handle when it is done. There are several good reasons not to do this. First, pathnames need separators between the directory com- ponents, and different operating systems use different sepa- rators. We could define a Network Standard Pathname Repre- sentation, but then every pathname would have to be parsed and converted at each end. Other issues are discussed in _N_F_S _I_m_p_l_e_m_e_n_t_a_t_i_o_n _I_s_s_u_e_s below. Although files and directories are similar objects in many ways, different procedures are used to read directories and files. This provides a network standard format for repre- senting directories. The same argument as above could have been used to justify a procedure that returns only one directory entry per call. The problem is efficiency. Directories can contain many entries, and a remote call to return each would be just too slow. 33..22.. RRPPCC IInnffoorrmmaattiioonn _A_u_t_h_e_n_t_i_c_a_t_i_o_n The NFS service uses _A_U_T_H___U_N_I_X, _A_U_T_H___D_E_S, or _A_U_T_H___S_H_O_R_T style authentication, except in the NULL procedure where _A_U_T_H___N_O_N_E is also allowed. _T_r_a_n_s_p_o_r_t _P_r_o_t_o_c_o_l_s NFS currently is supported on UDP/IP only. _P_o_r_t _N_u_m_b_e_r The NFS protocol currently uses the UDP port number 2049. This is not an officially assigned port, so later versions of the protocol use the "Portmapping" facility of RPC. 33..33.. SSiizzeess ooff XXDDRR SSttrruuccttuurreess These are the sizes, given in decimal bytes, of various XDR structures used in the protocol: Page 4 Network File System: Version 2 Protocol Specification /* _T_h_e _m_a_x_i_m_u_m _n_u_m_b_e_r _o_f _b_y_t_e_s _o_f _d_a_t_a _i_n _a _R_E_A_D _o_r _W_R_I_T_E _r_e_q_u_e_s_t */ const MAXDATA = 8192; /* _T_h_e _m_a_x_i_m_u_m _n_u_m_b_e_r _o_f _b_y_t_e_s _i_n _a _p_a_t_h_n_a_m_e _a_r_g_u_m_e_n_t */ const MAXPATHLEN = 1024; /* _T_h_e _m_a_x_i_m_u_m _n_u_m_b_e_r _o_f _b_y_t_e_s _i_n _a _f_i_l_e _n_a_m_e _a_r_g_u_m_e_n_t */ const MAXNAMLEN = 255; /* _T_h_e _s_i_z_e _i_n _b_y_t_e_s _o_f _t_h_e _o_p_a_q_u_e _"_c_o_o_k_i_e_" _p_a_s_s_e_d _b_y _R_E_A_D_D_I_R */ const COOKIESIZE = 4; /* _T_h_e _s_i_z_e _i_n _b_y_t_e_s _o_f _t_h_e _o_p_a_q_u_e _f_i_l_e _h_a_n_d_l_e */ const FHSIZE = 32; 33..44.. BBaassiicc DDaattaa TTyyppeess The following XDR definitions are basic structures and types used in other structures described further on. 33..44..11.. ssttaatt enum stat { NFS_OK = 0, NFSERR_PERM=1, NFSERR_NOENT=2, NFSERR_IO=5, NFSERR_NXIO=6, NFSERR_ACCES=13, NFSERR_EXIST=17, NFSERR_NODEV=19, NFSERR_NOTDIR=20, NFSERR_ISDIR=21, NFSERR_FBIG=27, NFSERR_NOSPC=28, NFSERR_ROFS=30, NFSERR_NAMETOOLONG=63, NFSERR_NOTEMPTY=66, NFSERR_DQUOT=69, NFSERR_STALE=70, NFSERR_WFLUSH=99 }; The _s_t_a_t type is returned with every procedure's results. A value of _N_F_S___O_K indicates that the call completed suc- cessfully and the results are valid. The other values indicate some kind of error occurred on the server side during the servicing of the procedure. The error values are derived from UNIX error numbers. NNFFSSEERRRR__PPEERRMM: Not owner. The caller does not have correct ownership Network File System: Version 2 Protocol Specification Page 5 to perform the requested operation. NNFFSSEERRRR__NNOOEENNTT: No such file or directory. The file or directory specified does not exist. NNFFSSEERRRR__IIOO: Some sort of hard error occurred when the operation was in progress. This could be a disk error, for exam- ple. NNFFSSEERRRR__NNXXIIOO: No such device or address. NNFFSSEERRRR__AACCCCEESS: Permission denied. The caller does not have the correct permission to perform the requested operation. NNFFSSEERRRR__EEXXIISSTT: File exists. The file specified already exists. NNFFSSEERRRR__NNOODDEEVV: No such device. NNFFSSEERRRR__NNOOTTDDIIRR: Not a directory. The caller specified a non- directory in a directory operation. NNFFSSEERRRR__IISSDDIIRR: Is a directory. The caller specified a directory in a non- directory operation. NNFFSSEERRRR__FFBBIIGG: File too large. The operation caused a file to grow beyond the server's limit. NNFFSSEERRRR__NNOOSSPPCC: No space left on device. The operation caused the server's filesystem to reach its limit. NNFFSSEERRRR__RROOFFSS: Read-only filesystem. Write attempted on a read-only filesystem. NNFFSSEERRRR__NNAAMMEETTOOOOLLOONNGG: File name too long. The file name in an opera- tion was too long. NNFFSSEERRRR__NNOOTTEEMMPPTTYY: Directory not empty. Attempted to remove a directory that was not empty. NNFFSSEERRRR__DDQQUUOOTT: Disk quota exceeded. The client's disk quota on the Page 6 Network File System: Version 2 Protocol Specification server has been exceeded. NNFFSSEERRRR__SSTTAALLEE: The "fhandle" given in the arguments was invalid. That is, the file referred to by that file handle no longer exists, or access to it has been revoked. NNFFSSEERRRR__WWFFLLUUSSHH: The server's write cache used in the _W_R_I_T_E_C_A_C_H_E call got flushed to disk. 33..44..22.. ffttyyppee enum ftype { NFNON = 0, NFREG = 1, NFDIR = 2, NFBLK = 3, NFCHR = 4, NFLNK = 5 }; The enumeration _f_t_y_p_e gives the type of a file. The type _N_F_N_O_N indicates a non-file, _N_F_R_E_G is a regular file, _N_F_D_I_R is a directory, _N_F_B_L_K is a block-special device, _N_F_C_H_R is a character-special device, and _N_F_L_N_K is a symbolic link. 33..44..33.. ffhhaannddllee typedef opaque fhandle[FHSIZE]; The _f_h_a_n_d_l_e is the file handle passed between the server and the client. All file operations are done using file handles to refer to a file or directory. The file handle can con- tain whatever information the server needs to distinguish an individual file. 33..44..44.. ttiimmeevvaall struct timeval { unsigned int seconds; unsigned int useconds; }; The _t_i_m_e_v_a_l structure is the number of seconds and microsec- onds since midnight January 1, 1970, Greenwich Mean Time. It is used to pass time and date information. Network File System: Version 2 Protocol Specification Page 7 33..44..55.. ffaattttrr struct fattr { ftype type; unsigned int mode; unsigned int nlink; unsigned int uid; unsigned int gid; unsigned int size; unsigned int blocksize; unsigned int rdev; unsigned int blocks; unsigned int fsid; unsigned int fileid; timeval atime; timeval mtime; timeval ctime; }; The _f_a_t_t_r structure contains the attributes of a file; "type" is the type of the file; "nlink" is the number of hard links to the file (the number of different names for the same file); "uid" is the user identification number of the owner of the file; "gid" is the group identification number of the group of the file; "size" is the size in bytes of the file; "blocksize" is the size in bytes of a block of the file; "rdev" is the device number of the file if it is type _N_F_C_H_R or _N_F_B_L_K; "blocks" is the number of blocks the file takes up on disk; "fsid" is the file system identifier for the filesystem containing the file; "fileid" is a number that uniquely identifies the file within its filesystem; "atime" is the time when the file was last accessed for either read or write; "mtime" is the time when the file data was last modified (written); and "ctime" is the time when the status of the file was last changed. Writing to the file also changes "ctime" if the size of the file changes. "mode" is the access mode encoded as a set of bits. Notice that the file type is specified both in the mode bits and in the file type. This is really a bug in the protocol and will be fixed in future versions. The descriptions given below specify the bit positions using octal numbers. Page 8 Network File System: Version 2 Protocol Specification +---------------------------------------------------------------------------+ | _B_i_t _D_e_s_c_r_i_p_t_i_o_n | +---------------------------------------------------------------------------+ |0040000 This is a directory; "type" field should be NFDIR. | |0020000 This is a character special file; "type" field should be NFCHR. | |0060000 This is a block special file; "type" field should be NFBLK. | |0100000 This is a regular file; "type" field should be NFREG. | |0120000 This is a symbolic link file; "type" field should be NFLNK. | |0140000 This is a named socket; "type" field should be NFNON. | |0004000 Set user id on execution. | |0002000 Set group id on execution. | |0001000 Save swapped text even after use. | |0000400 Read permission for owner. | |0000200 Write permission for owner. | |0000100 Execute and search permission for owner. | |0000040 Read permission for group. | |0000020 Write permission for group. | |0000010 Execute and search permission for group. | |0000004 Read permission for others. | |0000002 Write permission for others. | |0000001 Execute and search permission for others. | +---------------------------------------------------------------------------+ Notes: The bits are the same as the mode bits returned by the _s_t_a_t_(_2_) system call in the UNIX system. The file type is specified both in the mode bits and in the file type. This is fixed in future versions. The "rdev" field in the attributes structure is an operating system specific device specifier. It will be removed and generalized in the next revision of the protocol. 33..44..66.. ssaattttrr struct sattr { unsigned int mode; unsigned int uid; unsigned int gid; unsigned int size; timeval atime; timeval mtime; }; The _s_a_t_t_r structure contains the file attributes which can be set from the client. The fields are the same as for _f_a_t_t_r above. A "size" of zero means the file should be truncated. A value of -1 indicates a field that should be ignored. Network File System: Version 2 Protocol Specification Page 9 33..44..77.. ffiilleennaammee typedef string filename; The type _f_i_l_e_n_a_m_e is used for passing file names or path- name components. 33..44..88.. ppaatthh typedef string path; The type _p_a_t_h is a pathname. The server considers it as a string with no internal structure, but to the client it is the name of a node in a filesystem tree. 33..44..99.. aattttrrssttaatt union attrstat switch (stat status) { case NFS_OK: fattr attributes; default: void; }; The _a_t_t_r_s_t_a_t structure is a common procedure result. It contains a "status" and, if the call succeeded, it also contains the attributes of the file on which the oper- ation was done. 33..44..1100.. ddiirrooppaarrggss struct diropargs { fhandle dir; filename name; }; The _d_i_r_o_p_a_r_g_s structure is used in directory operations. The "fhandle" "dir" is the directory in which to find the file "name". A directory operation is one in which the directory is affected. Page 10Network File System: Version 2 Protocol Specification 33..44..1111.. ddiirroopprreess union diropres switch (stat status) { case NFS_OK: struct { fhandle file; fattr attributes; } diropok; default: void; }; The results of a directory operation are returned in a _d_i_r_o_p_r_e_s structure. If the call succeeded, a new file han- dle "file" and the "attributes" associated with that file are returned along with the "status". 33..55.. SSeerrvveerr PPrroocceedduurreess The protocol definition is given as a set of proce- dures with arguments and results defined using the RPC language. A brief description of the function of each pro- cedure should provide enough information to allow implemen- tation. All of the procedures in the NFS protocol are assumed to be synchronous. When a procedure returns to the client, the client can assume that the operation has com- pleted and any data associated with the request is now on stable storage. For example, a client _W_R_I_T_E request may cause the server to update data blocks, filesystem information blocks (such as indirect blocks), and file attribute information (size and modify times). When the _W_R_I_T_E returns to the client, it can assume that the write is safe, even in case of a server crash, and it can discard the data written. This is a very important part of the statelessness of the server. If the server waited to flush data from remote requests, the client would have to save those requests so that it could resend them in case of a server crash. Network File System: Version 2 Protocol SpecificationPage 11 _/_* _* _R_e_m_o_t_e _f_i_l_e _s_e_r_v_i_c_e _r_o_u_t_i_n_e_s _*_/ _p_r_o_g_r_a_m _N_F_S___P_R_O_G_R_A_M _{ _v_e_r_s_i_o_n _N_F_S___V_E_R_S_I_O_N _{ _v_o_i_d _N_F_S_P_R_O_C___N_U_L_L_(_v_o_i_d_) _= _0_; _a_t_t_r_s_t_a_t _N_F_S_P_R_O_C___G_E_T_A_T_T_R_(_f_h_a_n_d_l_e_) _= _1_; _a_t_t_r_s_t_a_t _N_F_S_P_R_O_C___S_E_T_A_T_T_R_(_s_a_t_t_r_a_r_g_s_) _= _2_; _v_o_i_d _N_F_S_P_R_O_C___R_O_O_T_(_v_o_i_d_) _= _3_; _d_i_r_o_p_r_e_s _N_F_S_P_R_O_C___L_O_O_K_U_P_(_d_i_r_o_p_a_r_g_s_) _= _4_; _r_e_a_d_l_i_n_k_r_e_s _N_F_S_P_R_O_C___R_E_A_D_L_I_N_K_(_f_h_a_n_d_l_e_) _= _5_; _r_e_a_d_r_e_s _N_F_S_P_R_O_C___R_E_A_D_(_r_e_a_d_a_r_g_s_) _= _6_; _v_o_i_d _N_F_S_P_R_O_C___W_R_I_T_E_C_A_C_H_E_(_v_o_i_d_) _= _7_; _a_t_t_r_s_t_a_t _N_F_S_P_R_O_C___W_R_I_T_E_(_w_r_i_t_e_a_r_g_s_) _= _8_; _d_i_r_o_p_r_e_s _N_F_S_P_R_O_C___C_R_E_A_T_E_(_c_r_e_a_t_e_a_r_g_s_) _= _9_; _s_t_a_t _N_F_S_P_R_O_C___R_E_M_O_V_E_(_d_i_r_o_p_a_r_g_s_) _= _1_0_; _s_t_a_t _N_F_S_P_R_O_C___R_E_N_A_M_E_(_r_e_n_a_m_e_a_r_g_s_) _= _1_1_; _s_t_a_t _N_F_S_P_R_O_C___L_I_N_K_(_l_i_n_k_a_r_g_s_) _= _1_2_; _s_t_a_t _N_F_S_P_R_O_C___S_Y_M_L_I_N_K_(_s_y_m_l_i_n_k_a_r_g_s_) _= _1_3_; _d_i_r_o_p_r_e_s _N_F_S_P_R_O_C___M_K_D_I_R_(_c_r_e_a_t_e_a_r_g_s_) _= _1_4_; _s_t_a_t _N_F_S_P_R_O_C___R_M_D_I_R_(_d_i_r_o_p_a_r_g_s_) _= _1_5_; _r_e_a_d_d_i_r_r_e_s _N_F_S_P_R_O_C___R_E_A_D_D_I_R_(_r_e_a_d_d_i_r_a_r_g_s_) _= _1_6_; _s_t_a_t_f_s_r_e_s _N_F_S_P_R_O_C___S_T_A_T_F_S_(_f_h_a_n_d_l_e_) _= _1_7_; _} _= _2_; _} _= _1_0_0_0_0_3_; 33..55..11.. DDoo NNootthhiinngg void NFSPROC_NULL(void) = 0; This procedure does no work. It is made available in all RPC services to allow server response testing and timing. 33..55..22.. GGeett FFiillee AAttttrriibbuutteess attrstat NFSPROC_GETATTR (fhandle) = 1; If the reply status is _N_F_S___O_K, then the reply attributes contains the attributes for the file given by the input fhandle. Page 12Network File System: Version 2 Protocol Specification 33..55..33.. SSeett FFiillee AAttttrriibbuutteess struct sattrargs { fhandle file; sattr attributes; }; attrstat NFSPROC_SETATTR (sattrargs) = 2; The "attributes" argument contains fields which are either -1 or are the new value for the attributes of "file". If the reply status is _N_F_S___O_K, then the reply attributes have the attributes of the file after the "SETATTR" opera- tion has completed. Note: The use of -1 to indicate an unused field in "attributes" is changed in the next version of the protocol. 33..55..44.. GGeett FFiilleessyysstteemm RRoooott void NFSPROC_ROOT(void) = 3; Obsolete. This procedure is no longer used because finding the root file handle of a filesystem requires moving pathnames between client and server. To do this right we would have to define a network standard representation of pathnames. Instead, the function of looking up the root file handle is done by the _M_N_T_P_R_O_C___M_N_T_(_) procedure. (See the _M_o_u_n_t _P_r_o_t_o_c_o_l _D_e_f_i_n_i_t_i_o_n later in this chapter for details). 33..55..55.. LLooookk UUpp FFiillee NNaammee diropres NFSPROC_LOOKUP(diropargs) = 4; If the reply "status" is _N_F_S___O_K, then the reply "file" and reply "attributes" are the file handle and attributes for the file "name" in the directory given by "dir" in the argument. Network File System: Version 2 Protocol SpecificationPage 13 33..55..66.. RReeaadd FFrroomm SSyymmbboolliicc LLiinnkk union readlinkres switch (stat status) { case NFS_OK: path data; default: void; }; readlinkres NFSPROC_READLINK(fhandle) = 5; If "status" has the value _N_F_S___O_K, then the reply "data" is the data in the symbolic link given by the file referred to by the fhandle argument. Note: since NFS always parses pathnames on the client, the pathname in a symbolic link may mean some- thing different (or be meaningless) on a different client or on the server if a different pathname syntax is used. 33..55..77.. RReeaadd FFrroomm FFiillee struct readargs { fhandle file; unsigned offset; unsigned count; unsigned totalcount; }; union readres switch (stat status) { case NFS_OK: fattr attributes; opaque data; default: void; }; readres NFSPROC_READ(readargs) = 6; Returns up to "count" bytes of "data" from the file given by "file", starting at "offset" bytes from the begin- ning of the file. The first byte of the file is at offset zero. The file attributes after the read takes place are returned in "attributes". Note: The argument "totalcount" is unused, and is removed in the next protocol revision. Page 14Network File System: Version 2 Protocol Specification 33..55..88.. WWrriittee ttoo CCaacchhee void NFSPROC_WRITECACHE(void) = 7; To be used in the next protocol revision. 33..55..99.. WWrriittee ttoo FFiillee struct writeargs { fhandle file; unsigned beginoffset; unsigned offset; unsigned totalcount; opaque data; }; attrstat NFSPROC_WRITE(writeargs) = 8; Writes "data" beginning "offset" bytes from the begin- ning of "file". The first byte of the file is at offset zero. If the reply "status" is NFS_OK, then the reply "attributes" contains the attributes of the file after the write has completed. The write operation is atomic. Data from this call to _W_R_I_T_E will not be mixed with data from another client's calls. Note: The arguments "beginoffset" and "totalcount" are ignored and are removed in the next protocol revision. 33..55..1100.. CCrreeaattee FFiillee struct createargs { diropargs where; sattr attributes; }; diropres NFSPROC_CREATE(createargs) = 9; The file "name" is created in the directory given by "dir". The initial attributes of the new file are given by "attributes". A reply "status" of NFS_OK indicates that the file was created, and reply "file" and reply "attributes" are its file handle and attributes. Any other reply "status" means that the operation failed and no file was created. Note: This routine should pass an exclusive create flag, meaning "create the file only if it is not already there". Network File System: Version 2 Protocol SpecificationPage 15 33..55..1111.. RReemmoovvee FFiillee stat NFSPROC_REMOVE(diropargs) = 10; The file "name" is removed from the directory given by "dir". A reply of NFS_OK means the directory entry was removed. Note: possibly non-idempotent operation. 33..55..1122.. RReennaammee FFiillee struct renameargs { diropargs from; diropargs to; }; stat NFSPROC_RENAME(renameargs) = 11; The existing file "from.name" in the directory given by "from.dir" is renamed to "to.name" in the directory given by "to.dir". If the reply is _N_F_S___O_K, the file was renamed. The RENAME operation is atomic on the server; it cannot be interrupted in the middle. Note: possibly non-idempotent operation. 33..55..1133.. CCrreeaattee LLiinnkk ttoo FFiillee struct linkargs { fhandle from; diropargs to; }; stat NFSPROC_LINK(linkargs) = 12; Creates the file "to.name" in the directory given by "to.dir", which is a hard link to the existing file given by "from". If the return value is _N_F_S___O_K, a link was cre- ated. Any other return value indicates an error, and the link was not created. A hard link should have the property that changes to either of the linked files are reflected in both files. When a hard link is made to a file, the attributes for the file should have a value for "nlink" that is one greater than the value before the link. Note: possibly non-idempotent operation. Page 16Network File System: Version 2 Protocol Specification 33..55..1144.. CCrreeaattee SSyymmbboolliicc LLiinnkk struct symlinkargs { diropargs from; path to; sattr attributes; }; stat NFSPROC_SYMLINK(symlinkargs) = 13; Creates the file "from.name" with ftype _N_F_L_N_K in the directory given by "from.dir". The new file contains the pathname "to" and has initial attributes given by "attributes". If the return value is _N_F_S___O_K, a link was created. Any other return value indicates an error, and the link was not created. A symbolic link is a pointer to another file. The name given in "to" is not interpreted by the server, only stored in the newly created file. When the client refer- ences a file that is a symbolic link, the contents of the symbolic link are normally transparently reinterpreted as a pathname to substitute. A _R_E_A_D_L_I_N_K operation returns the data to the client for interpretation. Note: On UNIX servers the attributes are never used, since symbolic links always have mode 0777. 33..55..1155.. CCrreeaattee DDiirreeccttoorryy diropres NFSPROC_MKDIR (createargs) = 14; The new directory "where.name" is created in the directory given by "where.dir". The initial attributes of the new directory are given by "attributes". A reply "status" of NFS_OK indicates that the new directory was created, and reply "file" and reply "attributes" are its file handle and attributes. Any other reply "status" means that the operation failed and no directory was created. Note: possibly non-idempotent operation. 33..55..1166.. RReemmoovvee DDiirreeccttoorryy stat NFSPROC_RMDIR(diropargs) = 15; The existing empty directory "name" in the directory given by "dir" is removed. If the reply is _N_F_S___O_K, the directory was removed. Network File System: Version 2 Protocol SpecificationPage 17 Note: possibly non-idempotent operation. 33..55..1177.. RReeaadd FFrroomm DDiirreeccttoorryy struct readdirargs { fhandle dir; nfscookie cookie; unsigned count; }; struct entry { unsigned fileid; filename name; nfscookie cookie; entry *nextentry; }; union readdirres switch (stat status) { case NFS_OK: struct { entry *entries; bool eof; } readdirok; default: void; }; readdirres NFSPROC_READDIR (readdirargs) = 16; Returns a variable number of directory entries, with a total size of up to "count" bytes, from the directory given by "dir". If the returned value of "status" is _N_F_S___O_K, then it is followed by a variable number of "entry"s. Each "entry" contains a "fileid" which consists of a unique number to identify the file within a filesystem, the "name" of the file, and a "cookie" which is an opaque pointer to the next entry in the directory. The cookie is used in the next _R_E_A_D_D_I_R call to get more entries starting at a given point in the directory. The special cookie zero (all bits zero) can be used to get the entries starting at the beginning of the directory. The "fileid" field should be the same number as the "fileid" in the the attributes of the file. (See the _B_a_s_i_c _D_a_t_a _T_y_p_e_s section.) The "eof" flag has a value of _T_R_U_E if there are no more entries in the directory. Page 18Network File System: Version 2 Protocol Specification 33..55..1188.. GGeett FFiilleessyysstteemm AAttttrriibbuutteess union statfsres (stat status) { case NFS_OK: struct { unsigned tsize; unsigned bsize; unsigned blocks; unsigned bfree; unsigned bavail; } info; default: void; }; statfsres NFSPROC_STATFS(fhandle) = 17; If the reply "status" is _N_F_S___O_K, then the reply "info" gives the attributes for the filesystem that contains file referred to by the input fhandle. The attribute fields con- tain the following values: tsize: The optimum transfer size of the server in bytes. This is the number of bytes the server would like to have in the data part of READ and WRITE requests. bsize: The block size in bytes of the filesystem. blocks: The total number of "bsize" blocks on the filesystem. bfree: The number of free "bsize" blocks on the filesystem. bavail: The number of "bsize" blocks available to non-privi- leged users. Note: This call does not work well if a filesystem has variable size blocks. 44.. NNFFSS IImmpplleemmeennttaattiioonn IIssssuueess The NFS protocol is designed to be operating system indepen- dent, but since this version was designed in a UNIX environ- ment, many operations have semantics similar to the opera- tions of the UNIX file system. This section discusses some of the implementation-specific semantic issues. Network File System: Version 2 Protocol SpecificationPage 19 44..11.. SSeerrvveerr//CClliieenntt RReellaattiioonnsshhiipp The NFS protocol is designed to allow servers to be as sim- ple and general as possible. Sometimes the simplicity of the server can be a problem, if the client wants to imple- ment complicated filesystem semantics. For example, some operating systems allow removal of open files. A process can open a file and, while it is open, remove it from the directory. The file can be read and written as long as the process keeps it open, even though the file has no name in the filesystem. It is impossible for a stateless server to implement these semantics. The client can do some tricks such as renaming the file on remove, and only removing it on close. We believe that the server provides enough functionality to implement most file system semantics on the client. Every NFS client can also potentially be a server, and remote and local mounted filesystems can be freely inter- mixed. This leads to some interesting problems when a client travels down the directory tree of a remote filesys- tem and reaches the mount point on the server for another remote filesystem. Allowing the server to follow the second remote mount would require loop detection, server lookup, and user revalidation. Instead, we decided not to let clients cross a server's mount point. When a client does a LOOKUP on a directory on which the server has mounted a filesystem, the client sees the underlying directory instead of the mounted directory. A client can do remote mounts that match the server's mount points to maintain the server's view. 44..22.. PPaatthhnnaammee IInntteerrpprreettaattiioonn There are a few complications to the rule that pathnames are always parsed on the client. For example, symbolic links could have different interpretations on different clients. Another common problem for non-UNIX implementations is the special interpretation of the pathname ".." to mean the parent of a given directory. The next revision of the pro- tocol uses an explicit flag to indicate the parent instead. 44..33.. PPeerrmmiissssiioonn IIssssuueess The NFS protocol, strictly speaking, does not define the permission checking used by servers. However, it is expected that a server will do normal operating system per- mission checking using _A_U_T_H___U_N_I_X style authentication as the basis of its protection mechanism. The server gets the client's effective "uid", effective "gid", and groups on each call and uses them to check permission. There are var- ious problems with this method that can been resolved in Page 20Network File System: Version 2 Protocol Specification interesting ways. Using "uid" and "gid" implies that the client and server share the same "uid" list. Every server and client pair must have the same mapping from user to "uid" and from group to "gid". Since every client can also be a server, this tends to imply that the whole network shares the same "uid/gid" space. _A_U_T_H___D_E_S (and the next revision of the NFS protocol) uses string names instead of numbers, but there are still complex problems to be solved. Another problem arises due to the usually stateful open operation. Most operating systems check permission at open time, and then check that the file is open on each read and write request. With stateless servers, the server has no idea that the file is open and must do permission checking on each read and write call. On a local filesystem, a user can open a file and then change the permissions so that no one is allowed to touch it, but will still be able to write to the file because it is open. On a remote filesystem, by contrast, the write would fail. To get around this problem, the server's permission checking algorithm should allow the owner of a file to access it regardless of the permission setting. A similar problem has to do with paging in from a file over the network. The operating system usually checks for exe- cute permission before opening a file for demand paging, and then reads blocks from the open file. The file may not have read permission, but after it is opened it doesn't matter. An NFS server can not tell the difference between a normal file read and a demand page-in read. To make this work, the server allows reading of files if the "uid" given in the call has execute or read permission on the file. In most operating systems, a particular user (on the user ID zero) has access to all files no matter what permission and ownership they have. This "super-user" permission may not be allowed on the server, since anyone who can become super- user on their workstation could gain access to all remote files. The UNIX server by default maps user id 0 to -2 before doing its access checking. This works except for NFS root filesystems, where super-user access cannot be avoided. 44..44.. SSeettttiinngg RRPPCC PPaarraammeetteerrss Various file system parameters and options should be set at mount time. The mount protocol is described in the appendix below. For example, "Soft" mounts as well as "Hard" mounts are usually both provided. Soft mounted file systems return errors when RPC operations fail (after a given number of optional retransmissions), while hard mounted file systems continue to retransmit forever. Clients and servers may need to keep caches of recent operations to help avoid Network File System: Version 2 Protocol SpecificationPage 21 problems with non-idempotent operations. 55.. MMoouunntt PPrroottooccooll DDeeffiinniittiioonn 55..11.. IInnttrroodduuccttiioonn The mount protocol is separate from, but related to, the NFS protocol. It provides operating system specific services to get the NFS off the ground -- looking up server path names, validating user identity, and checking access permissions. Clients use the mount protocol to get the first file handle, which allows them entry into a remote filesystem. The mount protocol is kept separate from the NFS protocol to make it easy to plug in new access checking and validation methods without changing the NFS server protocol. Notice that the protocol definition implies stateful servers because the server maintains a list of client's mount requests. The mount list information is not critical for the correct functioning of either the client or the server. It is intended for advisory use only, for example, to warn possible clients when a server is going down. Version one of the mount protocol is used with version two of the NFS protocol. The only connecting point is the _f_h_a_n_- _d_l_e structure, which is the same for both protocols. 55..22.. RRPPCC IInnffoorrmmaattiioonn _A_u_t_h_e_n_t_i_c_a_t_i_o_n The mount service uses _A_U_T_H___U_N_I_X and _A_U_T_H___D_E_S style authentication only. _T_r_a_n_s_p_o_r_t _P_r_o_t_o_c_o_l_s The mount service is currently supported on UDP/IP only. _P_o_r_t _N_u_m_b_e_r Consult the server's portmapper, described in the chap- ter _R_e_m_o_t_e _P_r_o_c_e_d_u_r_e _C_a_l_l_s_: _P_r_o_t_o_c_o_l _S_p_e_c_i_f_i_c_a_t_i_o_n, to find the port number on which the mount service is registered. 55..33.. SSiizzeess ooff XXDDRR SSttrruuccttuurreess These are the sizes, given in decimal bytes, of var- ious XDR structures used in the protocol: Page 22Network File System: Version 2 Protocol Specification /* _T_h_e _m_a_x_i_m_u_m _n_u_m_b_e_r _o_f _b_y_t_e_s _i_n _a _p_a_t_h_n_a_m_e _a_r_g_u_m_e_n_t */ const MNTPATHLEN = 1024; /* _T_h_e _m_a_x_i_m_u_m _n_u_m_b_e_r _o_f _b_y_t_e_s _i_n _a _n_a_m_e _a_r_g_u_m_e_n_t */ const MNTNAMLEN = 255; /* _T_h_e _s_i_z_e _i_n _b_y_t_e_s _o_f _t_h_e _o_p_a_q_u_e _f_i_l_e _h_a_n_d_l_e */ const FHSIZE = 32; 55..44.. BBaassiicc DDaattaa TTyyppeess This section presents the data types used by the mount protocol. In many cases they are similar to the types used in NFS. 55..44..11.. ffhhaannddllee typedef opaque fhandle[FHSIZE]; The type _f_h_a_n_d_l_e is the file handle that the server passes to the client. All file operations are done using file handles to refer to a file or directory. The file han- dle can contain whatever information the server needs to distinguish an individual file. This is the same as the "fhandle" XDR definition in ver- sion 2 of the NFS protocol; see _B_a_s_i_c _D_a_t_a _T_y_p_e_s in the definition of the NFS protocol, above. 55..44..22.. ffhhssttaattuuss union fhstatus switch (unsigned status) { case 0: fhandle directory; default: void; }; The type _f_h_s_t_a_t_u_s is a union. If a "status" of zero is returned, the call completed successfully, and a file handle for the "directory" follows. A non-zero sta- tus indicates some sort of error. In this case the status is a UNIX error number. 55..44..33.. ddiirrppaatthh typedef string dirpath; The type _d_i_r_p_a_t_h is a server pathname of a directory. Network File System: Version 2 Protocol SpecificationPage 23 55..44..44.. nnaammee typedef string name; The type _n_a_m_e is an arbitrary string used for various names. 55..55.. SSeerrvveerr PPrroocceedduurreess The following sections define the RPC procedures supplied by a mount server. _/_* _* _P_r_o_t_o_c_o_l _d_e_s_c_r_i_p_t_i_o_n _f_o_r _t_h_e _m_o_u_n_t _p_r_o_g_r_a_m _*_/ _p_r_o_g_r_a_m _M_O_U_N_T_P_R_O_G _{ _/_* _* _V_e_r_s_i_o_n _1 _o_f _t_h_e _m_o_u_n_t _p_r_o_t_o_c_o_l _u_s_e_d _w_i_t_h _* _v_e_r_s_i_o_n _2 _o_f _t_h_e _N_F_S _p_r_o_t_o_c_o_l_. _*_/ _v_e_r_s_i_o_n _M_O_U_N_T_V_E_R_S _{ _v_o_i_d _M_O_U_N_T_P_R_O_C___N_U_L_L_(_v_o_i_d_) _= _0_; _f_h_s_t_a_t_u_s _M_O_U_N_T_P_R_O_C___M_N_T_(_d_i_r_p_a_t_h_) _= _1_; _m_o_u_n_t_l_i_s_t _M_O_U_N_T_P_R_O_C___D_U_M_P_(_v_o_i_d_) _= _2_; _v_o_i_d _M_O_U_N_T_P_R_O_C___U_M_N_T_(_d_i_r_p_a_t_h_) _= _3_; _v_o_i_d _M_O_U_N_T_P_R_O_C___U_M_N_T_A_L_L_(_v_o_i_d_) _= _4_; _e_x_p_o_r_t_l_i_s_t _M_O_U_N_T_P_R_O_C___E_X_P_O_R_T_(_v_o_i_d_) _= _5_; _} _= _1_; _} _= _1_0_0_0_0_5_; 55..55..11.. DDoo NNootthhiinngg void MNTPROC_NULL(void) = 0; This procedure does no work. It is made available in all RPC services to allow server response testing and tim- ing. 55..55..22.. AAdddd MMoouunntt EEnnttrryy fhstatus MNTPROC_MNT(dirpath) = 1; If the reply "status" is 0, then the reply "directory" con- tains the file handle for the directory "dirname". This file handle may be used in the NFS protocol. This procedure also adds a new entry to the mount list for this client mounting "dirname". Page 24Network File System: Version 2 Protocol Specification 55..55..33.. RReettuurrnn MMoouunntt EEnnttrriieess struct *mountlist { name hostname; dirpath directory; mountlist nextentry; }; mountlist MNTPROC_DUMP(void) = 2; Returns the list of remote mounted filesystems. The "mountlist" contains one entry for each "hostname" and "directory" pair. 55..55..44.. RReemmoovvee MMoouunntt EEnnttrryy void MNTPROC_UMNT(dirpath) = 3; Removes the mount list entry for the input "dirpath". 55..55..55.. RReemmoovvee AAllll MMoouunntt EEnnttrriieess void MNTPROC_UMNTALL(void) = 4; Removes all of the mount list entries for this client. 55..55..66.. RReettuurrnn EExxppoorrtt LLiisstt struct *groups { name grname; groups grnext; }; struct *exportlist { dirpath filesys; groups groups; exportlist next; }; exportlist MNTPROC_EXPORT(void) = 5; Returns a variable number of export list entries. Each entry contains a filesystem name and a list of groups that are allowed to import it. The filesystem name is in "filesys", and the group name is in the list "groups". Note: The exportlist should contain more information about the status of the filesystem, such as a read-only flag.