2 .\" Must use -- tbl -- with this one
4 .\" @(#)nfs.rfc.ms 2.2 88/08/05 4.0 RPCSRC
8 .if \\n%=1 .tl ''- % -''
11 .\" prevent excess underlining in nroff
13 .OH 'Network File System: Version 2 Protocol Specification''Page %'
14 .EH 'Page %''Network File System: Version 2 Protocol Specification'
17 \&Network File System: Version 2 Protocol Specification
18 .IX NFS "" "" "" PAGE MAJOR
19 .IX "Network File System" "" "" "" PAGE MAJOR
20 .IX NFS "version-2 protocol specification"
21 .IX "Network File System" "version-2 protocol specification"
24 \&Status of this Standard
26 Note: This document specifies a protocol that Sun Microsystems, Inc.,
27 and others are using. It specifies it in standard ARPA RFC form.
32 The Sun Network Filesystem (NFS) protocol provides transparent remote
33 access to shared filesystems over local area networks. The NFS
34 protocol is designed to be machine, operating system, network architecture,
35 and transport protocol independent. This independence is
36 achieved through the use of Remote Procedure Call (RPC) primitives
37 built on top of an External Data Representation (XDR). Implementations
38 exist for a variety of machines, from personal computers to
41 The supporting mount protocol allows the server to hand out remote
42 access privileges to a restricted set of clients. It performs the
43 operating system-specific functions that allow, for example, to
44 attach remote directory trees to some local file system.
46 \&Remote Procedure Call
47 .IX "Remote Procedure Call"
49 Sun's remote procedure call specification provides a procedure-
50 oriented interface to remote services. Each server supplies a
51 program that is a set of procedures. NFS is one such "program".
52 The combination of host address, program number, and procedure
53 number specifies one remote service procedure. RPC does not depend
54 on services provided by specific protocols, so it can be used with
55 any underlying transport protocol. See the
56 .I "Remote Procedure Calls: Protocol Specification"
57 chapter of this manual.
59 \&External Data Representation
60 .IX "External Data Representation"
62 The External Data Representation (XDR) standard provides a common
63 way of representing a set of data types over a network.
65 Protocol Specification is written using the RPC data description
67 For more information, see the
68 .I " External Data Representation Standard: Protocol Specification."
69 Sun provides implementations of XDR and
70 RPC, but NFS does not require their use. Any software that
71 provides equivalent functionality can be used, and if the encoding
72 is exactly the same it can interoperate with other implementations
76 .IX "stateless servers"
79 The NFS protocol is stateless. That is, a server does not need to
80 maintain any extra state information about any of its clients in
81 order to function correctly. Stateless servers have a distinct
82 advantage over stateful servers in the event of a failure. With
83 stateless servers, a client need only retry a request until the
84 server responds; it does not even need to know that the server has
85 crashed, or the network temporarily went down. The client of a
86 stateful server, on the other hand, needs to either detect a server
87 crash and rebuild the server's state when it comes back up, or
88 cause client operations to fail.
90 This may not sound like an important issue, but it affects the
91 protocol in some unexpected ways. We feel that it is worth a bit
92 of extra complexity in the protocol to be able to write very simple
93 servers that do not require fancy crash recovery.
95 On the other hand, NFS deals with objects such as files and
96 directories that inherently have state -- what good would a file be
97 if it did not keep its contents intact? The goal is to not
98 introduce any extra state in the protocol itself. Another way to
99 simplify recovery is by making operations "idempotent" whenever
100 possible (so that they can potentially be repeated).
102 \&NFS Protocol Definition
103 .IX NFS "protocol definition"
106 Servers have been known to change over time, and so can the
107 protocol that they use. So RPC provides a version number with each
108 RPC request. This RFC describes version two of the NFS protocol.
109 Even in the second version, there are various obsolete procedures
110 and parameters, which will be removed in later versions. An RFC
111 for version three of the NFS protocol is currently under
117 NFS assumes a file system that is hierarchical, with directories as
118 all but the bottom-level files. Each entry in a directory (file,
119 directory, device, etc.) has a string name. Different operating
120 systems may have restrictions on the depth of the tree or the names
121 used, as well as using different syntax to represent the "pathname",
122 which is the concatenation of all the "components" (directory and
123 file names) in the name. A "file system" is a tree on a single
124 server (usually a single disk or physical partition) with a specified
125 "root". Some operating systems provide a "mount" operation to make
126 all file systems appear as a single tree, while others maintain a
127 "forest" of file systems. Files are unstructured streams of
128 uninterpreted bytes. Version 3 of NFS uses a slightly more general
131 NFS looks up one component of a pathname at a time. It may not be
132 obvious why it does not just take the whole pathname, traipse down
133 the directories, and return a file handle when it is done. There are
134 several good reasons not to do this. First, pathnames need
135 separators between the directory components, and different operating
136 systems use different separators. We could define a Network Standard
137 Pathname Representation, but then every pathname would have to be
138 parsed and converted at each end. Other issues are discussed in
139 \fINFS Implementation Issues\fP below.
141 Although files and directories are similar objects in many ways,
142 different procedures are used to read directories and files. This
143 provides a network standard format for representing directories. The
144 same argument as above could have been used to justify a procedure
145 that returns only one directory entry per call. The problem is
146 efficiency. Directories can contain many entries, and a remote call
147 to return each would be just too slow.
150 .IX NFS "RPC information"
151 .IP \fIAuthentication\fP
158 authentication, except in the NULL procedure where
161 .IP "\fITransport Protocols\fP"
162 NFS currently is supported on UDP/IP only.
163 .IP "\fIPort Number\fP"
164 The NFS protocol currently uses the UDP port number 2049. This is
165 not an officially assigned port, so later versions of the protocol
166 use the \*QPortmapping\*U facility of RPC.
168 \&Sizes of XDR Structures
169 .IX "XDR structure sizes"
171 These are the sizes, given in decimal bytes, of various XDR
172 structures used in the protocol:
174 /* \fIThe maximum number of bytes of data in a READ or WRITE request\fP */
175 const MAXDATA = 8192;
177 /* \fIThe maximum number of bytes in a pathname argument\fP */
178 const MAXPATHLEN = 1024;
180 /* \fIThe maximum number of bytes in a file name argument\fP */
181 const MAXNAMLEN = 255;
183 /* \fIThe size in bytes of the opaque "cookie" passed by READDIR\fP */
184 const COOKIESIZE = 4;
186 /* \fIThe size in bytes of the opaque file handle\fP */
192 .IX NFS "basic data types"
194 The following XDR definitions are basic structures and types used
195 in other structures described further on.
199 .IX "NFS data types" stat "" \fIstat\fP
215 NFSERR_NAMETOOLONG=63,
226 type is returned with every procedure's results. A
229 indicates that the call completed successfully and
230 the results are valid. The other values indicate some kind of
231 error occurred on the server side during the servicing of the
232 procedure. The error values are derived from UNIX error numbers.
233 .IP \fBNFSERR_PERM\fP:
234 Not owner. The caller does not have correct ownership
235 to perform the requested operation.
236 .IP \fBNFSERR_NOENT\fP:
237 No such file or directory. The file or directory
238 specified does not exist.
240 Some sort of hard error occurred when the operation was
241 in progress. This could be a disk error, for example.
242 .IP \fBNFSERR_NXIO\fP:
243 No such device or address.
244 .IP \fBNFSERR_ACCES\fP:
245 Permission denied. The caller does not have the
246 correct permission to perform the requested operation.
247 .IP \fBNFSERR_EXIST\fP:
248 File exists. The file specified already exists.
249 .IP \fBNFSERR_NODEV\fP:
251 .IP \fBNFSERR_NOTDIR\fP:
252 Not a directory. The caller specified a
253 non-directory in a directory operation.
254 .IP \fBNFSERR_ISDIR\fP:
255 Is a directory. The caller specified a directory in
256 a non- directory operation.
257 .IP \fBNFSERR_FBIG\fP:
258 File too large. The operation caused a file to grow
259 beyond the server's limit.
260 .IP \fBNFSERR_NOSPC\fP:
261 No space left on device. The operation caused the
262 server's filesystem to reach its limit.
263 .IP \fBNFSERR_ROFS\fP:
264 Read-only filesystem. Write attempted on a read-only filesystem.
265 .IP \fBNFSERR_NAMETOOLONG\fP:
266 File name too long. The file name in an operation was too long.
267 .IP \fBNFSERR_NOTEMPTY\fP:
268 Directory not empty. Attempted to remove a
269 directory that was not empty.
270 .IP \fBNFSERR_DQUOT\fP:
271 Disk quota exceeded. The client's disk quota on the
272 server has been exceeded.
273 .IP \fBNFSERR_STALE\fP:
274 The "fhandle" given in the arguments was invalid.
275 That is, the file referred to by that file handle no longer exists,
276 or access to it has been revoked.
277 .IP \fBNFSERR_WFLUSH\fP:
278 The server's write cache used in the
280 call got flushed to disk.
285 .IX "NFS data types" ftype "" \fIftype\fP
299 gives the type of a file. The type
301 indicates a non-file,
307 is a block-special device,
309 is a character-special device, and
315 .IX "NFS data types" fhandle "" \fIfhandle\fP
317 typedef opaque fhandle[FHSIZE];
322 is the file handle passed between the server and the client.
323 All file operations are done using file handles to refer to a file or
324 directory. The file handle can contain whatever information the server
325 needs to distinguish an individual file.
329 .IX "NFS data types" timeval "" \fItimeval\fP
332 unsigned int seconds;
333 unsigned int useconds;
339 structure is the number of seconds and microseconds
340 since midnight January 1, 1970, Greenwich Mean Time. It is used to
341 pass time and date information.
345 .IX "NFS data types" fattr "" \fIfattr\fP
354 unsigned int blocksize;
367 structure contains the attributes of a file; "type" is the type of
368 the file; "nlink" is the number of hard links to the file (the number
369 of different names for the same file); "uid" is the user
370 identification number of the owner of the file; "gid" is the group
371 identification number of the group of the file; "size" is the size in
372 bytes of the file; "blocksize" is the size in bytes of a block of the
373 file; "rdev" is the device number of the file if it is type
377 "blocks" is the number of blocks the file takes up on disk; "fsid" is
378 the file system identifier for the filesystem containing the file;
379 "fileid" is a number that uniquely identifies the file within its
380 filesystem; "atime" is the time when the file was last accessed for
381 either read or write; "mtime" is the time when the file data was last
382 modified (written); and "ctime" is the time when the status of the
383 file was last changed. Writing to the file also changes "ctime" if
384 the size of the file changes.
386 "mode" is the access mode encoded as a set of bits. Notice that the
387 file type is specified both in the mode bits and in the file type.
388 This is really a bug in the protocol and will be fixed in future
389 versions. The descriptions given below specify the bit positions
397 0040000&This is a directory; "type" field should be NFDIR.
398 0020000&This is a character special file; "type" field should be NFCHR.
399 0060000&This is a block special file; "type" field should be NFBLK.
400 0100000&This is a regular file; "type" field should be NFREG.
401 0120000&This is a symbolic link file; "type" field should be NFLNK.
402 0140000&This is a named socket; "type" field should be NFNON.
403 0004000&Set user id on execution.
404 0002000&Set group id on execution.
405 0001000&Save swapped text even after use.
406 0000400&Read permission for owner.
407 0000200&Write permission for owner.
408 0000100&Execute and search permission for owner.
409 0000040&Read permission for group.
410 0000020&Write permission for group.
411 0000010&Execute and search permission for group.
412 0000004&Read permission for others.
413 0000002&Write permission for others.
414 0000001&Execute and search permission for others.
419 The bits are the same as the mode bits returned by the
421 system call in the UNIX system. The file type is specified both in
422 the mode bits and in the file type. This is fixed in future
425 The "rdev" field in the attributes structure is an operating system
426 specific device specifier. It will be removed and generalized in
427 the next revision of the protocol.
433 .IX "NFS data types" sattr "" \fIsattr\fP
447 structure contains the file attributes which can be set
448 from the client. The fields are the same as for
450 above. A "size" of zero means the file should be truncated.
451 A value of -1 indicates a field that should be ignored.
456 .IX "NFS data types" filename "" \fIfilename\fP
458 typedef string filename<MAXNAMLEN>;
463 is used for passing file names or pathname components.
468 .IX "NFS data types" path "" \fIpath\fP
470 typedef string path<MAXPATHLEN>;
475 is a pathname. The server considers it as a string
476 with no internal structure, but to the client it is the name of a
477 node in a filesystem tree.
482 .IX "NFS data types" attrstat "" \fIattrstat\fP
484 union attrstat switch (stat status) {
494 structure is a common procedure result. It contains
495 a "status" and, if the call succeeded, it also contains the
496 attributes of the file on which the operation was done.
501 .IX "NFS data types" diropargs "" \fIdiropargs\fP
511 structure is used in directory operations. The
512 "fhandle" "dir" is the directory in which to find the file "name".
513 A directory operation is one in which the directory is affected.
518 .IX "NFS data types" diropres "" \fIdiropres\fP
520 union diropres switch (stat status) {
531 The results of a directory operation are returned in a
533 structure. If the call succeeded, a new file handle "file" and the
534 "attributes" associated with that file are returned along with the
538 .IX "NFS server procedures" "" "" "" PAGE MAJOR
540 The protocol definition is given as a set of procedures with
541 arguments and results defined using the RPC language. A brief
542 description of the function of each procedure should provide enough
543 information to allow implementation.
545 All of the procedures in the NFS protocol are assumed to be
546 synchronous. When a procedure returns to the client, the client
547 can assume that the operation has completed and any data associated
548 with the request is now on stable storage. For example, a client
550 request may cause the server to update data blocks,
551 filesystem information blocks (such as indirect blocks), and file
552 attribute information (size and modify times). When the
554 returns to the client, it can assume that the write is safe, even
555 in case of a server crash, and it can discard the data written.
556 This is a very important part of the statelessness of the server.
557 If the server waited to flush data from remote requests, the client
558 would have to save those requests so that it could resend them in
559 case of a server crash.
565 * Remote file service routines
568 program NFS_PROGRAM {
569 version NFS_VERSION {
570 void NFSPROC_NULL(void) = 0;
571 attrstat NFSPROC_GETATTR(fhandle) = 1;
572 attrstat NFSPROC_SETATTR(sattrargs) = 2;
573 void NFSPROC_ROOT(void) = 3;
574 diropres NFSPROC_LOOKUP(diropargs) = 4;
575 readlinkres NFSPROC_READLINK(fhandle) = 5;
576 readres NFSPROC_READ(readargs) = 6;
577 void NFSPROC_WRITECACHE(void) = 7;
578 attrstat NFSPROC_WRITE(writeargs) = 8;
579 diropres NFSPROC_CREATE(createargs) = 9;
580 stat NFSPROC_REMOVE(diropargs) = 10;
581 stat NFSPROC_RENAME(renameargs) = 11;
582 stat NFSPROC_LINK(linkargs) = 12;
583 stat NFSPROC_SYMLINK(symlinkargs) = 13;
584 diropres NFSPROC_MKDIR(createargs) = 14;
585 stat NFSPROC_RMDIR(diropargs) = 15;
586 readdirres NFSPROC_READDIR(readdirargs) = 16;
587 statfsres NFSPROC_STATFS(fhandle) = 17;
594 .IX "NFS server procedures" NFSPROC_NULL() "" \fINFSPROC_NULL()\fP
597 NFSPROC_NULL(void) = 0;
600 This procedure does no work. It is made available in all RPC
601 services to allow server response testing and timing.
604 \&Get File Attributes
605 .IX "NFS server procedures" NFSPROC_GETATTR() "" \fINFSPROC_GETATTR()\fP
608 NFSPROC_GETATTR (fhandle) = 1;
611 If the reply status is
613 then the reply attributes contains
614 the attributes for the file given by the input fhandle.
617 \&Set File Attributes
618 .IX "NFS server procedures" NFSPROC_SETATTR() "" \fINFSPROC_SETATTR()\fP
626 NFSPROC_SETATTR (sattrargs) = 2;
629 The "attributes" argument contains fields which are either -1 or
630 are the new value for the attributes of "file". If the reply
633 then the reply attributes have the attributes of
634 the file after the "SETATTR" operation has completed.
636 Note: The use of -1 to indicate an unused field in "attributes" is
637 changed in the next version of the protocol.
640 \&Get Filesystem Root
641 .IX "NFS server procedures" NFSPROC_ROOT "" \fINFSPROC_ROOT\fP
644 NFSPROC_ROOT(void) = 3;
647 Obsolete. This procedure is no longer used because finding the
648 root file handle of a filesystem requires moving pathnames between
649 client and server. To do this right we would have to define a
650 network standard representation of pathnames. Instead, the
651 function of looking up the root file handle is done by the
654 .I "Mount Protocol Definition"
655 later in this chapter for details).
659 .IX "NFS server procedures" NFSPROC_LOOKUP() "" \fINFSPROC_LOOKUP()\fP
662 NFSPROC_LOOKUP(diropargs) = 4;
665 If the reply "status" is
667 then the reply "file" and reply
668 "attributes" are the file handle and attributes for the file "name"
669 in the directory given by "dir" in the argument.
672 \&Read From Symbolic Link
673 .IX "NFS server procedures" NFSPROC_READLINK() "" \fINFSPROC_READLINK()\fP
675 union readlinkres switch (stat status) {
683 NFSPROC_READLINK(fhandle) = 5;
686 If "status" has the value
688 then the reply "data" is the data in
689 the symbolic link given by the file referred to by the fhandle argument.
691 Note: since NFS always parses pathnames on the client, the
692 pathname in a symbolic link may mean something different (or be
693 meaningless) on a different client or on the server if a different
694 pathname syntax is used.
698 .IX "NFS server procedures" NFSPROC_READ "" \fINFSPROC_READ\fP
707 union readres switch (stat status) {
710 opaque data<NFS_MAXDATA>;
716 NFSPROC_READ(readargs) = 6;
719 Returns up to "count" bytes of "data" from the file given by
720 "file", starting at "offset" bytes from the beginning of the file.
721 The first byte of the file is at offset zero. The file attributes
722 after the read takes place are returned in "attributes".
724 Note: The argument "totalcount" is unused, and is removed in the
725 next protocol revision.
729 .IX "NFS server procedures" NFSPROC_WRITECACHE() "" \fINFSPROC_WRITECACHE()\fP
732 NFSPROC_WRITECACHE(void) = 7;
735 To be used in the next protocol revision.
739 .IX "NFS server procedures" NFSPROC_WRITE() "" \fINFSPROC_WRITE()\fP
743 unsigned beginoffset;
746 opaque data<NFS_MAXDATA>;
750 NFSPROC_WRITE(writeargs) = 8;
753 Writes "data" beginning "offset" bytes from the beginning of
754 "file". The first byte of the file is at offset zero. If the
755 reply "status" is NFS_OK, then the reply "attributes" contains the
756 attributes of the file after the write has completed. The write
757 operation is atomic. Data from this call to
759 will not be mixed with data from another client's calls.
761 Note: The arguments "beginoffset" and "totalcount" are ignored and
762 are removed in the next protocol revision.
766 .IX "NFS server procedures" NFSPROC_CREATE() "" \fINFSPROC_CREATE()\fP
774 NFSPROC_CREATE(createargs) = 9;
777 The file "name" is created in the directory given by "dir". The
778 initial attributes of the new file are given by "attributes". A
779 reply "status" of NFS_OK indicates that the file was created, and
780 reply "file" and reply "attributes" are its file handle and
781 attributes. Any other reply "status" means that the operation
782 failed and no file was created.
784 Note: This routine should pass an exclusive create flag, meaning
785 "create the file only if it is not already there".
789 .IX "NFS server procedures" NFSPROC_REMOVE() "" \fINFSPROC_REMOVE()\fP
792 NFSPROC_REMOVE(diropargs) = 10;
795 The file "name" is removed from the directory given by "dir". A
796 reply of NFS_OK means the directory entry was removed.
798 Note: possibly non-idempotent operation.
802 .IX "NFS server procedures" NFSPROC_RENAME() "" \fINFSPROC_RENAME()\fP
810 NFSPROC_RENAME(renameargs) = 11;
813 The existing file "from.name" in the directory given by "from.dir"
814 is renamed to "to.name" in the directory given by "to.dir". If the
817 the file was renamed. The
820 atomic on the server; it cannot be interrupted in the middle.
822 Note: possibly non-idempotent operation.
825 \&Create Link to File
826 .IX "NFS server procedures" NFSPROC_LINK() "" \fINFSPROC_LINK()\fP
834 NFSPROC_LINK(linkargs) = 12;
837 Creates the file "to.name" in the directory given by "to.dir",
838 which is a hard link to the existing file given by "from". If the
841 a link was created. Any other return value
842 indicates an error, and the link was not created.
844 A hard link should have the property that changes to either of the
845 linked files are reflected in both files. When a hard link is made
846 to a file, the attributes for the file should have a value for
847 "nlink" that is one greater than the value before the link.
849 Note: possibly non-idempotent operation.
852 \&Create Symbolic Link
853 .IX "NFS server procedures" NFSPROC_SYMLINK() "" \fINFSPROC_SYMLINK()\fP
862 NFSPROC_SYMLINK(symlinkargs) = 13;
865 Creates the file "from.name" with ftype
868 given by "from.dir". The new file contains the pathname "to" and
869 has initial attributes given by "attributes". If the return value
872 a link was created. Any other return value indicates an
873 error, and the link was not created.
875 A symbolic link is a pointer to another file. The name given in
876 "to" is not interpreted by the server, only stored in the newly
877 created file. When the client references a file that is a symbolic
878 link, the contents of the symbolic link are normally transparently
879 reinterpreted as a pathname to substitute. A
881 operation returns the data to the client for interpretation.
883 Note: On UNIX servers the attributes are never used, since
884 symbolic links always have mode 0777.
888 .IX "NFS server procedures" NFSPROC_MKDIR() "" \fINFSPROC_MKDIR()\fP
891 NFSPROC_MKDIR (createargs) = 14;
894 The new directory "where.name" is created in the directory given by
895 "where.dir". The initial attributes of the new directory are given
896 by "attributes". A reply "status" of NFS_OK indicates that the new
897 directory was created, and reply "file" and reply "attributes" are
898 its file handle and attributes. Any other reply "status" means
899 that the operation failed and no directory was created.
901 Note: possibly non-idempotent operation.
905 .IX "NFS server procedures" NFSPROC_RMDIR() "" \fINFSPROC_RMDIR()\fP
908 NFSPROC_RMDIR(diropargs) = 15;
911 The existing empty directory "name" in the directory given by "dir"
912 is removed. If the reply is
914 the directory was removed.
916 Note: possibly non-idempotent operation.
919 \&Read From Directory
920 .IX "NFS server procedures" NFSPROC_READDIR() "" \fINFSPROC_READDIR()\fP
935 union readdirres switch (stat status) {
946 NFSPROC_READDIR (readdirargs) = 16;
949 Returns a variable number of directory entries, with a total size
950 of up to "count" bytes, from the directory given by "dir". If the
951 returned value of "status" is
953 then it is followed by a
954 variable number of "entry"s. Each "entry" contains a "fileid"
955 which consists of a unique number to identify the file within a
956 filesystem, the "name" of the file, and a "cookie" which is an
957 opaque pointer to the next entry in the directory. The cookie is
960 call to get more entries starting at a
961 given point in the directory. The special cookie zero (all bits
962 zero) can be used to get the entries starting at the beginning of
963 the directory. The "fileid" field should be the same number as the
964 "fileid" in the attributes of the file. (See the
965 .I "Basic Data Types"
967 The "eof" flag has a value of
969 if there are no more entries in the directory.
972 \&Get Filesystem Attributes
973 .IX "NFS server procedures" NFSPROC_STATFS() "" \fINFSPROC_STATFS()\fP
975 union statfsres (stat status) {
989 NFSPROC_STATFS(fhandle) = 17;
992 If the reply "status" is
994 then the reply "info" gives the
995 attributes for the filesystem that contains file referred to by the
996 input fhandle. The attribute fields contain the following values:
998 The optimum transfer size of the server in bytes. This is
999 the number of bytes the server would like to have in the
1000 data part of READ and WRITE requests.
1002 The block size in bytes of the filesystem.
1004 The total number of "bsize" blocks on the filesystem.
1006 The number of free "bsize" blocks on the filesystem.
1008 The number of "bsize" blocks available to non-privileged users.
1010 Note: This call does not work well if a filesystem has variable
1013 \&NFS Implementation Issues
1014 .IX NFS implementation
1016 The NFS protocol is designed to be operating system independent, but
1017 since this version was designed in a UNIX environment, many
1018 operations have semantics similar to the operations of the UNIX file
1019 system. This section discusses some of the implementation-specific
1022 \&Server/Client Relationship
1023 .IX NFS "server/client relationship"
1025 The NFS protocol is designed to allow servers to be as simple and
1026 general as possible. Sometimes the simplicity of the server can be a
1027 problem, if the client wants to implement complicated filesystem
1030 For example, some operating systems allow removal of open files. A
1031 process can open a file and, while it is open, remove it from the
1032 directory. The file can be read and written as long as the process
1033 keeps it open, even though the file has no name in the filesystem.
1034 It is impossible for a stateless server to implement these semantics.
1035 The client can do some tricks such as renaming the file on remove,
1036 and only removing it on close. We believe that the server provides
1037 enough functionality to implement most file system semantics on the
1040 Every NFS client can also potentially be a server, and remote and
1041 local mounted filesystems can be freely intermixed. This leads to
1042 some interesting problems when a client travels down the directory
1043 tree of a remote filesystem and reaches the mount point on the server
1044 for another remote filesystem. Allowing the server to follow the
1045 second remote mount would require loop detection, server lookup, and
1046 user revalidation. Instead, we decided not to let clients cross a
1047 server's mount point. When a client does a LOOKUP on a directory on
1048 which the server has mounted a filesystem, the client sees the
1049 underlying directory instead of the mounted directory. A client can
1050 do remote mounts that match the server's mount points to maintain the
1054 \&Pathname Interpretation
1055 .IX NFS "pathname interpretation"
1057 There are a few complications to the rule that pathnames are always
1058 parsed on the client. For example, symbolic links could have
1059 different interpretations on different clients. Another common
1060 problem for non-UNIX implementations is the special interpretation of
1061 the pathname ".." to mean the parent of a given directory. The next
1062 revision of the protocol uses an explicit flag to indicate the parent
1066 .IX NFS "permission issues"
1068 The NFS protocol, strictly speaking, does not define the permission
1069 checking used by servers. However, it is expected that a server
1070 will do normal operating system permission checking using
1072 style authentication as the basis of its protection mechanism. The
1073 server gets the client's effective "uid", effective "gid", and groups
1074 on each call and uses them to check permission. There are various
1075 problems with this method that can been resolved in interesting ways.
1077 Using "uid" and "gid" implies that the client and server share the
1078 same "uid" list. Every server and client pair must have the same
1079 mapping from user to "uid" and from group to "gid". Since every
1080 client can also be a server, this tends to imply that the whole
1081 network shares the same "uid/gid" space.
1084 revision of the NFS protocol) uses string names instead of numbers,
1085 but there are still complex problems to be solved.
1087 Another problem arises due to the usually stateful open operation.
1088 Most operating systems check permission at open time, and then check
1089 that the file is open on each read and write request. With stateless
1090 servers, the server has no idea that the file is open and must do
1091 permission checking on each read and write call. On a local
1092 filesystem, a user can open a file and then change the permissions so
1093 that no one is allowed to touch it, but will still be able to write
1094 to the file because it is open. On a remote filesystem, by contrast,
1095 the write would fail. To get around this problem, the server's
1096 permission checking algorithm should allow the owner of a file to
1097 access it regardless of the permission setting.
1099 A similar problem has to do with paging in from a file over the
1100 network. The operating system usually checks for execute permission
1101 before opening a file for demand paging, and then reads blocks from
1102 the open file. The file may not have read permission, but after it
1103 is opened it doesn't matter. An NFS server can not tell the
1104 difference between a normal file read and a demand page-in read. To
1105 make this work, the server allows reading of files if the "uid" given
1106 in the call has execute or read permission on the file.
1108 In most operating systems, a particular user (on the user ID zero)
1109 has access to all files no matter what permission and ownership they
1110 have. This "super-user" permission may not be allowed on the server,
1111 since anyone who can become super-user on their workstation could
1112 gain access to all remote files. The UNIX server by default maps
1113 user id 0 to -2 before doing its access checking. This works except
1114 for NFS root filesystems, where super-user access cannot be avoided.
1116 \&Setting RPC Parameters
1117 .IX NFS "setting RPC parameters"
1119 Various file system parameters and options should be set at mount
1120 time. The mount protocol is described in the appendix below. For
1121 example, "Soft" mounts as well as "Hard" mounts are usually both
1122 provided. Soft mounted file systems return errors when RPC
1123 operations fail (after a given number of optional retransmissions),
1124 while hard mounted file systems continue to retransmit forever.
1125 Clients and servers may need to keep caches of recent operations to
1126 help avoid problems with non-idempotent operations.
1128 \&Mount Protocol Definition
1129 .IX "mount protocol" "" "" "" PAGE MAJOR
1133 .IX "mount protocol" introduction
1135 The mount protocol is separate from, but related to, the NFS
1136 protocol. It provides operating system specific services to get the
1137 NFS off the ground -- looking up server path names, validating user
1138 identity, and checking access permissions. Clients use the mount
1139 protocol to get the first file handle, which allows them entry into a
1142 The mount protocol is kept separate from the NFS protocol to make it
1143 easy to plug in new access checking and validation methods without
1144 changing the NFS server protocol.
1146 Notice that the protocol definition implies stateful servers because
1147 the server maintains a list of client's mount requests. The mount
1148 list information is not critical for the correct functioning of
1149 either the client or the server. It is intended for advisory use
1150 only, for example, to warn possible clients when a server is going
1153 Version one of the mount protocol is used with version two of the NFS
1154 protocol. The only connecting point is the
1156 structure, which is the same for both protocols.
1159 .IX "mount protocol" "RPC information"
1160 .IP \fIAuthentication\fP
1161 The mount service uses
1165 style authentication only.
1166 .IP "\fITransport Protocols\fP"
1167 The mount service is currently supported on UDP/IP only.
1168 .IP "\fIPort Number\fP"
1169 Consult the server's portmapper, described in the chapter
1170 .I "Remote Procedure Calls: Protocol Specification",
1171 to find the port number on which the mount service is registered.
1173 \&Sizes of XDR Structures
1174 .IX "mount protocol" "XDR structure sizes"
1176 These are the sizes, given in decimal bytes, of various XDR
1177 structures used in the protocol:
1179 /* \fIThe maximum number of bytes in a pathname argument\fP */
1180 const MNTPATHLEN = 1024;
1182 /* \fIThe maximum number of bytes in a name argument\fP */
1183 const MNTNAMLEN = 255;
1185 /* \fIThe size in bytes of the opaque file handle\fP */
1190 .IX "mount protocol" "basic data types"
1191 .IX "mount data types"
1193 This section presents the data types used by the mount protocol.
1194 In many cases they are similar to the types used in NFS.
1198 .IX "mount data types" fhandle "" \fIfhandle\fP
1200 typedef opaque fhandle[FHSIZE];
1205 is the file handle that the server passes to the
1206 client. All file operations are done using file handles to refer
1207 to a file or directory. The file handle can contain whatever
1208 information the server needs to distinguish an individual file.
1210 This is the same as the "fhandle" XDR definition in version 2 of
1211 the NFS protocol; see
1212 .I "Basic Data Types"
1213 in the definition of the NFS protocol, above.
1217 .IX "mount data types" fhstatus "" \fIfhstatus\fP
1219 union fhstatus switch (unsigned status) {
1229 is a union. If a "status" of zero is returned,
1230 the call completed successfully, and a file handle for the
1231 "directory" follows. A non-zero status indicates some sort of
1232 error. In this case the status is a UNIX error number.
1236 .IX "mount data types" dirpath "" \fIdirpath\fP
1238 typedef string dirpath<MNTPATHLEN>;
1243 is a server pathname of a directory.
1247 .IX "mount data types" name "" \fIname\fP
1249 typedef string name<MNTNAMLEN>;
1254 is an arbitrary string used for various names.
1257 .IX "mount server procedures"
1259 The following sections define the RPC procedures supplied by a
1265 * Protocol description for the mount program
1272 * Version 1 of the mount protocol used with
1273 * version 2 of the NFS protocol.
1277 void MOUNTPROC_NULL(void) = 0;
1278 fhstatus MOUNTPROC_MNT(dirpath) = 1;
1279 mountlist MOUNTPROC_DUMP(void) = 2;
1280 void MOUNTPROC_UMNT(dirpath) = 3;
1281 void MOUNTPROC_UMNTALL(void) = 4;
1282 exportlist MOUNTPROC_EXPORT(void) = 5;
1289 .IX "mount server procedures" MNTPROC_NULL() "" \fIMNTPROC_NULL()\fP
1292 MNTPROC_NULL(void) = 0;
1295 This procedure does no work. It is made available in all RPC
1296 services to allow server response testing and timing.
1300 .IX "mount server procedures" MNTPROC_MNT() "" \fIMNTPROC_MNT()\fP
1303 MNTPROC_MNT(dirpath) = 1;
1306 If the reply "status" is 0, then the reply "directory" contains the
1307 file handle for the directory "dirname". This file handle may be
1308 used in the NFS protocol. This procedure also adds a new entry to
1309 the mount list for this client mounting "dirname".
1312 \&Return Mount Entries
1313 .IX "mount server procedures" MNTPROC_DUMP() "" \fIMNTPROC_DUMP()\fP
1318 mountlist nextentry;
1322 MNTPROC_DUMP(void) = 2;
1325 Returns the list of remote mounted filesystems. The "mountlist"
1326 contains one entry for each "hostname" and "directory" pair.
1329 \&Remove Mount Entry
1330 .IX "mount server procedures" MNTPROC_UMNT() "" \fIMNTPROC_UMNT()\fP
1333 MNTPROC_UMNT(dirpath) = 3;
1336 Removes the mount list entry for the input "dirpath".
1339 \&Remove All Mount Entries
1340 .IX "mount server procedures" MNTPROC_UMNTALL() "" \fIMNTPROC_UMNTALL()\fP
1343 MNTPROC_UMNTALL(void) = 4;
1346 Removes all of the mount list entries for this client.
1349 \&Return Export List
1350 .IX "mount server procedures" MNTPROC_EXPORT() "" \fIMNTPROC_EXPORT()\fP
1357 struct *exportlist {
1364 MNTPROC_EXPORT(void) = 5;
1367 Returns a variable number of export list entries. Each entry
1368 contains a filesystem name and a list of groups that are allowed to
1369 import it. The filesystem name is in "filesys", and the group name
1370 is in the list "groups".
1372 Note: The exportlist should contain
1373 more information about the status of the filesystem, such as a
projects / FreeBSD / releng / 10.0.git / blob