2 .\" Must use -- tbl -- with this one
4 .\" @(#)nfs.rfc.ms 2.2 88/08/05 4.0 RPCSRC
5 .\" $FreeBSD: src/lib/libc/rpc/PSD.doc/nfs.rfc.ms,v 1.1.14.1 2000/11/24 09:36:30 ru Exp $
6 .\" $DragonFly: src/lib/libc/rpc/PSD.doc/nfs.rfc.ms,v 1.2 2003/06/17 04:26:45 dillon Exp $
10 .if \\n%=1 .tl ''- % -''
13 .\" prevent excess underlining in nroff
15 .OH 'Network File System: Version 2 Protocol Specification''Page %'
16 .EH 'Page %''Network File System: Version 2 Protocol Specification'
19 \&Network File System: Version 2 Protocol Specification
20 .IX NFS "" "" "" PAGE MAJOR
21 .IX "Network File System" "" "" "" PAGE MAJOR
22 .IX NFS "version-2 protocol specification"
23 .IX "Network File System" "version-2 protocol specification"
26 \&Status of this Standard
28 Note: This document specifies a protocol that Sun Microsystems, Inc.,
29 and others are using. It specifies it in standard ARPA RFC form.
34 The Sun Network Filesystem (NFS) protocol provides transparent remote
35 access to shared filesystems over local area networks. The NFS
36 protocol is designed to be machine, operating system, network architecture,
37 and transport protocol independent. This independence is
38 achieved through the use of Remote Procedure Call (RPC) primitives
39 built on top of an External Data Representation (XDR). Implementations
40 exist for a variety of machines, from personal computers to
43 The supporting mount protocol allows the server to hand out remote
44 access privileges to a restricted set of clients. It performs the
45 operating system-specific functions that allow, for example, to
46 attach remote directory trees to some local file system.
48 \&Remote Procedure Call
49 .IX "Remote Procedure Call"
51 Sun's remote procedure call specification provides a procedure-
52 oriented interface to remote services. Each server supplies a
53 program that is a set of procedures. NFS is one such "program".
54 The combination of host address, program number, and procedure
55 number specifies one remote service procedure. RPC does not depend
56 on services provided by specific protocols, so it can be used with
57 any underlying transport protocol. See the
58 .I "Remote Procedure Calls: Protocol Specification"
59 chapter of this manual.
61 \&External Data Representation
62 .IX "External Data Representation"
64 The External Data Representation (XDR) standard provides a common
65 way of representing a set of data types over a network.
67 Protocol Specification is written using the RPC data description
69 For more information, see the
70 .I " External Data Representation Standard: Protocol Specification."
71 Sun provides implementations of XDR and
72 RPC, but NFS does not require their use. Any software that
73 provides equivalent functionality can be used, and if the encoding
74 is exactly the same it can interoperate with other implementations
78 .IX "stateless servers"
81 The NFS protocol is stateless. That is, a server does not need to
82 maintain any extra state information about any of its clients in
83 order to function correctly. Stateless servers have a distinct
84 advantage over stateful servers in the event of a failure. With
85 stateless servers, a client need only retry a request until the
86 server responds; it does not even need to know that the server has
87 crashed, or the network temporarily went down. The client of a
88 stateful server, on the other hand, needs to either detect a server
89 crash and rebuild the server's state when it comes back up, or
90 cause client operations to fail.
92 This may not sound like an important issue, but it affects the
93 protocol in some unexpected ways. We feel that it is worth a bit
94 of extra complexity in the protocol to be able to write very simple
95 servers that do not require fancy crash recovery.
97 On the other hand, NFS deals with objects such as files and
98 directories that inherently have state -- what good would a file be
99 if it did not keep its contents intact? The goal is to not
100 introduce any extra state in the protocol itself. Another way to
101 simplify recovery is by making operations "idempotent" whenever
102 possible (so that they can potentially be repeated).
104 \&NFS Protocol Definition
105 .IX NFS "protocol definition"
108 Servers have been known to change over time, and so can the
109 protocol that they use. So RPC provides a version number with each
110 RPC request. This RFC describes version two of the NFS protocol.
111 Even in the second version, there are various obsolete procedures
112 and parameters, which will be removed in later versions. An RFC
113 for version three of the NFS protocol is currently under
119 NFS assumes a file system that is hierarchical, with directories as
120 all but the bottom-level files. Each entry in a directory (file,
121 directory, device, etc.) has a string name. Different operating
122 systems may have restrictions on the depth of the tree or the names
123 used, as well as using different syntax to represent the "pathname",
124 which is the concatenation of all the "components" (directory and
125 file names) in the name. A "file system" is a tree on a single
126 server (usually a single disk or physical partition) with a specified
127 "root". Some operating systems provide a "mount" operation to make
128 all file systems appear as a single tree, while others maintain a
129 "forest" of file systems. Files are unstructured streams of
130 uninterpreted bytes. Version 3 of NFS uses a slightly more general
133 NFS looks up one component of a pathname at a time. It may not be
134 obvious why it does not just take the whole pathname, traipse down
135 the directories, and return a file handle when it is done. There are
136 several good reasons not to do this. First, pathnames need
137 separators between the directory components, and different operating
138 systems use different separators. We could define a Network Standard
139 Pathname Representation, but then every pathname would have to be
140 parsed and converted at each end. Other issues are discussed in
141 \fINFS Implementation Issues\fP below.
143 Although files and directories are similar objects in many ways,
144 different procedures are used to read directories and files. This
145 provides a network standard format for representing directories. The
146 same argument as above could have been used to justify a procedure
147 that returns only one directory entry per call. The problem is
148 efficiency. Directories can contain many entries, and a remote call
149 to return each would be just too slow.
152 .IX NFS "RPC information"
153 .IP \fIAuthentication\fP
160 authentication, except in the NULL procedure where
163 .IP "\fITransport Protocols\fP"
164 NFS currently is supported on UDP/IP only.
165 .IP "\fIPort Number\fP"
166 The NFS protocol currently uses the UDP port number 2049. This is
167 not an officially assigned port, so later versions of the protocol
168 use the \*QPortmapping\*U facility of RPC.
170 \&Sizes of XDR Structures
171 .IX "XDR structure sizes"
173 These are the sizes, given in decimal bytes, of various XDR
174 structures used in the protocol:
176 /* \fIThe maximum number of bytes of data in a READ or WRITE request\fP */
177 const MAXDATA = 8192;
179 /* \fIThe maximum number of bytes in a pathname argument\fP */
180 const MAXPATHLEN = 1024;
182 /* \fIThe maximum number of bytes in a file name argument\fP */
183 const MAXNAMLEN = 255;
185 /* \fIThe size in bytes of the opaque "cookie" passed by READDIR\fP */
186 const COOKIESIZE = 4;
188 /* \fIThe size in bytes of the opaque file handle\fP */
194 .IX NFS "basic data types"
196 The following XDR definitions are basic structures and types used
197 in other structures described further on.
201 .IX "NFS data types" stat "" \fIstat\fP
217 NFSERR_NAMETOOLONG=63,
228 type is returned with every procedure's results. A
231 indicates that the call completed successfully and
232 the results are valid. The other values indicate some kind of
233 error occurred on the server side during the servicing of the
234 procedure. The error values are derived from UNIX error numbers.
235 .IP \fBNFSERR_PERM\fP:
236 Not owner. The caller does not have correct ownership
237 to perform the requested operation.
238 .IP \fBNFSERR_NOENT\fP:
239 No such file or directory. The file or directory
240 specified does not exist.
242 Some sort of hard error occurred when the operation was
243 in progress. This could be a disk error, for example.
244 .IP \fBNFSERR_NXIO\fP:
245 No such device or address.
246 .IP \fBNFSERR_ACCES\fP:
247 Permission denied. The caller does not have the
248 correct permission to perform the requested operation.
249 .IP \fBNFSERR_EXIST\fP:
250 File exists. The file specified already exists.
251 .IP \fBNFSERR_NODEV\fP:
253 .IP \fBNFSERR_NOTDIR\fP:
254 Not a directory. The caller specified a
255 non-directory in a directory operation.
256 .IP \fBNFSERR_ISDIR\fP:
257 Is a directory. The caller specified a directory in
258 a non- directory operation.
259 .IP \fBNFSERR_FBIG\fP:
260 File too large. The operation caused a file to grow
261 beyond the server's limit.
262 .IP \fBNFSERR_NOSPC\fP:
263 No space left on device. The operation caused the
264 server's filesystem to reach its limit.
265 .IP \fBNFSERR_ROFS\fP:
266 Read-only filesystem. Write attempted on a read-only filesystem.
267 .IP \fBNFSERR_NAMETOOLONG\fP:
268 File name too long. The file name in an operation was too long.
269 .IP \fBNFSERR_NOTEMPTY\fP:
270 Directory not empty. Attempted to remove a
271 directory that was not empty.
272 .IP \fBNFSERR_DQUOT\fP:
273 Disk quota exceeded. The client's disk quota on the
274 server has been exceeded.
275 .IP \fBNFSERR_STALE\fP:
276 The "fhandle" given in the arguments was invalid.
277 That is, the file referred to by that file handle no longer exists,
278 or access to it has been revoked.
279 .IP \fBNFSERR_WFLUSH\fP:
280 The server's write cache used in the
282 call got flushed to disk.
287 .IX "NFS data types" ftype "" \fIftype\fP
301 gives the type of a file. The type
303 indicates a non-file,
309 is a block-special device,
311 is a character-special device, and
317 .IX "NFS data types" fhandle "" \fIfhandle\fP
319 typedef opaque fhandle[FHSIZE];
324 is the file handle passed between the server and the client.
325 All file operations are done using file handles to refer to a file or
326 directory. The file handle can contain whatever information the server
327 needs to distinguish an individual file.
331 .IX "NFS data types" timeval "" \fItimeval\fP
334 unsigned int seconds;
335 unsigned int useconds;
341 structure is the number of seconds and microseconds
342 since midnight January 1, 1970, Greenwich Mean Time. It is used to
343 pass time and date information.
347 .IX "NFS data types" fattr "" \fIfattr\fP
356 unsigned int blocksize;
369 structure contains the attributes of a file; "type" is the type of
370 the file; "nlink" is the number of hard links to the file (the number
371 of different names for the same file); "uid" is the user
372 identification number of the owner of the file; "gid" is the group
373 identification number of the group of the file; "size" is the size in
374 bytes of the file; "blocksize" is the size in bytes of a block of the
375 file; "rdev" is the device number of the file if it is type
379 "blocks" is the number of blocks the file takes up on disk; "fsid" is
380 the file system identifier for the filesystem containing the file;
381 "fileid" is a number that uniquely identifies the file within its
382 filesystem; "atime" is the time when the file was last accessed for
383 either read or write; "mtime" is the time when the file data was last
384 modified (written); and "ctime" is the time when the status of the
385 file was last changed. Writing to the file also changes "ctime" if
386 the size of the file changes.
388 "mode" is the access mode encoded as a set of bits. Notice that the
389 file type is specified both in the mode bits and in the file type.
390 This is really a bug in the protocol and will be fixed in future
391 versions. The descriptions given below specify the bit positions
399 0040000&This is a directory; "type" field should be NFDIR.
400 0020000&This is a character special file; "type" field should be NFCHR.
401 0060000&This is a block special file; "type" field should be NFBLK.
402 0100000&This is a regular file; "type" field should be NFREG.
403 0120000&This is a symbolic link file; "type" field should be NFLNK.
404 0140000&This is a named socket; "type" field should be NFNON.
405 0004000&Set user id on execution.
406 0002000&Set group id on execution.
407 0001000&Save swapped text even after use.
408 0000400&Read permission for owner.
409 0000200&Write permission for owner.
410 0000100&Execute and search permission for owner.
411 0000040&Read permission for group.
412 0000020&Write permission for group.
413 0000010&Execute and search permission for group.
414 0000004&Read permission for others.
415 0000002&Write permission for others.
416 0000001&Execute and search permission for others.
421 The bits are the same as the mode bits returned by the
423 system call in the UNIX system. The file type is specified both in
424 the mode bits and in the file type. This is fixed in future
427 The "rdev" field in the attributes structure is an operating system
428 specific device specifier. It will be removed and generalized in
429 the next revision of the protocol.
435 .IX "NFS data types" sattr "" \fIsattr\fP
449 structure contains the file attributes which can be set
450 from the client. The fields are the same as for
452 above. A "size" of zero means the file should be truncated.
453 A value of -1 indicates a field that should be ignored.
458 .IX "NFS data types" filename "" \fIfilename\fP
460 typedef string filename<MAXNAMLEN>;
465 is used for passing file names or pathname components.
470 .IX "NFS data types" path "" \fIpath\fP
472 typedef string path<MAXPATHLEN>;
477 is a pathname. The server considers it as a string
478 with no internal structure, but to the client it is the name of a
479 node in a filesystem tree.
484 .IX "NFS data types" attrstat "" \fIattrstat\fP
486 union attrstat switch (stat status) {
496 structure is a common procedure result. It contains
497 a "status" and, if the call succeeded, it also contains the
498 attributes of the file on which the operation was done.
503 .IX "NFS data types" diropargs "" \fIdiropargs\fP
513 structure is used in directory operations. The
514 "fhandle" "dir" is the directory in which to find the file "name".
515 A directory operation is one in which the directory is affected.
520 .IX "NFS data types" diropres "" \fIdiropres\fP
522 union diropres switch (stat status) {
533 The results of a directory operation are returned in a
535 structure. If the call succeeded, a new file handle "file" and the
536 "attributes" associated with that file are returned along with the
540 .IX "NFS server procedures" "" "" "" PAGE MAJOR
542 The protocol definition is given as a set of procedures with
543 arguments and results defined using the RPC language. A brief
544 description of the function of each procedure should provide enough
545 information to allow implementation.
547 All of the procedures in the NFS protocol are assumed to be
548 synchronous. When a procedure returns to the client, the client
549 can assume that the operation has completed and any data associated
550 with the request is now on stable storage. For example, a client
552 request may cause the server to update data blocks,
553 filesystem information blocks (such as indirect blocks), and file
554 attribute information (size and modify times). When the
556 returns to the client, it can assume that the write is safe, even
557 in case of a server crash, and it can discard the data written.
558 This is a very important part of the statelessness of the server.
559 If the server waited to flush data from remote requests, the client
560 would have to save those requests so that it could resend them in
561 case of a server crash.
567 * Remote file service routines
570 program NFS_PROGRAM {
571 version NFS_VERSION {
572 void NFSPROC_NULL(void) = 0;
573 attrstat NFSPROC_GETATTR(fhandle) = 1;
574 attrstat NFSPROC_SETATTR(sattrargs) = 2;
575 void NFSPROC_ROOT(void) = 3;
576 diropres NFSPROC_LOOKUP(diropargs) = 4;
577 readlinkres NFSPROC_READLINK(fhandle) = 5;
578 readres NFSPROC_READ(readargs) = 6;
579 void NFSPROC_WRITECACHE(void) = 7;
580 attrstat NFSPROC_WRITE(writeargs) = 8;
581 diropres NFSPROC_CREATE(createargs) = 9;
582 stat NFSPROC_REMOVE(diropargs) = 10;
583 stat NFSPROC_RENAME(renameargs) = 11;
584 stat NFSPROC_LINK(linkargs) = 12;
585 stat NFSPROC_SYMLINK(symlinkargs) = 13;
586 diropres NFSPROC_MKDIR(createargs) = 14;
587 stat NFSPROC_RMDIR(diropargs) = 15;
588 readdirres NFSPROC_READDIR(readdirargs) = 16;
589 statfsres NFSPROC_STATFS(fhandle) = 17;
596 .IX "NFS server procedures" NFSPROC_NULL() "" \fINFSPROC_NULL()\fP
599 NFSPROC_NULL(void) = 0;
602 This procedure does no work. It is made available in all RPC
603 services to allow server response testing and timing.
606 \&Get File Attributes
607 .IX "NFS server procedures" NFSPROC_GETATTR() "" \fINFSPROC_GETATTR()\fP
610 NFSPROC_GETATTR (fhandle) = 1;
613 If the reply status is
615 then the reply attributes contains
616 the attributes for the file given by the input fhandle.
619 \&Set File Attributes
620 .IX "NFS server procedures" NFSPROC_SETATTR() "" \fINFSPROC_SETATTR()\fP
628 NFSPROC_SETATTR (sattrargs) = 2;
631 The "attributes" argument contains fields which are either -1 or
632 are the new value for the attributes of "file". If the reply
635 then the reply attributes have the attributes of
636 the file after the "SETATTR" operation has completed.
638 Note: The use of -1 to indicate an unused field in "attributes" is
639 changed in the next version of the protocol.
642 \&Get Filesystem Root
643 .IX "NFS server procedures" NFSPROC_ROOT "" \fINFSPROC_ROOT\fP
646 NFSPROC_ROOT(void) = 3;
649 Obsolete. This procedure is no longer used because finding the
650 root file handle of a filesystem requires moving pathnames between
651 client and server. To do this right we would have to define a
652 network standard representation of pathnames. Instead, the
653 function of looking up the root file handle is done by the
656 .I "Mount Protocol Definition"
657 later in this chapter for details).
661 .IX "NFS server procedures" NFSPROC_LOOKUP() "" \fINFSPROC_LOOKUP()\fP
664 NFSPROC_LOOKUP(diropargs) = 4;
667 If the reply "status" is
669 then the reply "file" and reply
670 "attributes" are the file handle and attributes for the file "name"
671 in the directory given by "dir" in the argument.
674 \&Read From Symbolic Link
675 .IX "NFS server procedures" NFSPROC_READLINK() "" \fINFSPROC_READLINK()\fP
677 union readlinkres switch (stat status) {
685 NFSPROC_READLINK(fhandle) = 5;
688 If "status" has the value
690 then the reply "data" is the data in
691 the symbolic link given by the file referred to by the fhandle argument.
693 Note: since NFS always parses pathnames on the client, the
694 pathname in a symbolic link may mean something different (or be
695 meaningless) on a different client or on the server if a different
696 pathname syntax is used.
700 .IX "NFS server procedures" NFSPROC_READ "" \fINFSPROC_READ\fP
709 union readres switch (stat status) {
712 opaque data<NFS_MAXDATA>;
718 NFSPROC_READ(readargs) = 6;
721 Returns up to "count" bytes of "data" from the file given by
722 "file", starting at "offset" bytes from the beginning of the file.
723 The first byte of the file is at offset zero. The file attributes
724 after the read takes place are returned in "attributes".
726 Note: The argument "totalcount" is unused, and is removed in the
727 next protocol revision.
731 .IX "NFS server procedures" NFSPROC_WRITECACHE() "" \fINFSPROC_WRITECACHE()\fP
734 NFSPROC_WRITECACHE(void) = 7;
737 To be used in the next protocol revision.
741 .IX "NFS server procedures" NFSPROC_WRITE() "" \fINFSPROC_WRITE()\fP
745 unsigned beginoffset;
748 opaque data<NFS_MAXDATA>;
752 NFSPROC_WRITE(writeargs) = 8;
755 Writes "data" beginning "offset" bytes from the beginning of
756 "file". The first byte of the file is at offset zero. If the
757 reply "status" is NFS_OK, then the reply "attributes" contains the
758 attributes of the file after the write has completed. The write
759 operation is atomic. Data from this call to
761 will not be mixed with data from another client's calls.
763 Note: The arguments "beginoffset" and "totalcount" are ignored and
764 are removed in the next protocol revision.
768 .IX "NFS server procedures" NFSPROC_CREATE() "" \fINFSPROC_CREATE()\fP
776 NFSPROC_CREATE(createargs) = 9;
779 The file "name" is created in the directory given by "dir". The
780 initial attributes of the new file are given by "attributes". A
781 reply "status" of NFS_OK indicates that the file was created, and
782 reply "file" and reply "attributes" are its file handle and
783 attributes. Any other reply "status" means that the operation
784 failed and no file was created.
786 Note: This routine should pass an exclusive create flag, meaning
787 "create the file only if it is not already there".
791 .IX "NFS server procedures" NFSPROC_REMOVE() "" \fINFSPROC_REMOVE()\fP
794 NFSPROC_REMOVE(diropargs) = 10;
797 The file "name" is removed from the directory given by "dir". A
798 reply of NFS_OK means the directory entry was removed.
800 Note: possibly non-idempotent operation.
804 .IX "NFS server procedures" NFSPROC_RENAME() "" \fINFSPROC_RENAME()\fP
812 NFSPROC_RENAME(renameargs) = 11;
815 The existing file "from.name" in the directory given by "from.dir"
816 is renamed to "to.name" in the directory given by "to.dir". If the
819 the file was renamed. The
822 atomic on the server; it cannot be interrupted in the middle.
824 Note: possibly non-idempotent operation.
827 \&Create Link to File
828 .IX "NFS server procedures" NFSPROC_LINK() "" \fINFSPROC_LINK()\fP
836 NFSPROC_LINK(linkargs) = 12;
839 Creates the file "to.name" in the directory given by "to.dir",
840 which is a hard link to the existing file given by "from". If the
843 a link was created. Any other return value
844 indicates an error, and the link was not created.
846 A hard link should have the property that changes to either of the
847 linked files are reflected in both files. When a hard link is made
848 to a file, the attributes for the file should have a value for
849 "nlink" that is one greater than the value before the link.
851 Note: possibly non-idempotent operation.
854 \&Create Symbolic Link
855 .IX "NFS server procedures" NFSPROC_SYMLINK() "" \fINFSPROC_SYMLINK()\fP
864 NFSPROC_SYMLINK(symlinkargs) = 13;
867 Creates the file "from.name" with ftype
870 given by "from.dir". The new file contains the pathname "to" and
871 has initial attributes given by "attributes". If the return value
874 a link was created. Any other return value indicates an
875 error, and the link was not created.
877 A symbolic link is a pointer to another file. The name given in
878 "to" is not interpreted by the server, only stored in the newly
879 created file. When the client references a file that is a symbolic
880 link, the contents of the symbolic link are normally transparently
881 reinterpreted as a pathname to substitute. A
883 operation returns the data to the client for interpretation.
885 Note: On UNIX servers the attributes are never used, since
886 symbolic links always have mode 0777.
890 .IX "NFS server procedures" NFSPROC_MKDIR() "" \fINFSPROC_MKDIR()\fP
893 NFSPROC_MKDIR (createargs) = 14;
896 The new directory "where.name" is created in the directory given by
897 "where.dir". The initial attributes of the new directory are given
898 by "attributes". A reply "status" of NFS_OK indicates that the new
899 directory was created, and reply "file" and reply "attributes" are
900 its file handle and attributes. Any other reply "status" means
901 that the operation failed and no directory was created.
903 Note: possibly non-idempotent operation.
907 .IX "NFS server procedures" NFSPROC_RMDIR() "" \fINFSPROC_RMDIR()\fP
910 NFSPROC_RMDIR(diropargs) = 15;
913 The existing empty directory "name" in the directory given by "dir"
914 is removed. If the reply is
916 the directory was removed.
918 Note: possibly non-idempotent operation.
921 \&Read From Directory
922 .IX "NFS server procedures" NFSPROC_READDIR() "" \fINFSPROC_READDIR()\fP
937 union readdirres switch (stat status) {
948 NFSPROC_READDIR (readdirargs) = 16;
951 Returns a variable number of directory entries, with a total size
952 of up to "count" bytes, from the directory given by "dir". If the
953 returned value of "status" is
955 then it is followed by a
956 variable number of "entry"s. Each "entry" contains a "fileid"
957 which consists of a unique number to identify the file within a
958 filesystem, the "name" of the file, and a "cookie" which is an
959 opaque pointer to the next entry in the directory. The cookie is
962 call to get more entries starting at a
963 given point in the directory. The special cookie zero (all bits
964 zero) can be used to get the entries starting at the beginning of
965 the directory. The "fileid" field should be the same number as the
966 "fileid" in the the attributes of the file. (See the
967 .I "Basic Data Types"
969 The "eof" flag has a value of
971 if there are no more entries in the directory.
974 \&Get Filesystem Attributes
975 .IX "NFS server procedures" NFSPROC_STATFS() "" \fINFSPROC_STATFS()\fP
977 union statfsres (stat status) {
991 NFSPROC_STATFS(fhandle) = 17;
994 If the reply "status" is
996 then the reply "info" gives the
997 attributes for the filesystem that contains file referred to by the
998 input fhandle. The attribute fields contain the following values:
1000 The optimum transfer size of the server in bytes. This is
1001 the number of bytes the server would like to have in the
1002 data part of READ and WRITE requests.
1004 The block size in bytes of the filesystem.
1006 The total number of "bsize" blocks on the filesystem.
1008 The number of free "bsize" blocks on the filesystem.
1010 The number of "bsize" blocks available to non-privileged users.
1012 Note: This call does not work well if a filesystem has variable
1015 \&NFS Implementation Issues
1016 .IX NFS implementation
1018 The NFS protocol is designed to be operating system independent, but
1019 since this version was designed in a UNIX environment, many
1020 operations have semantics similar to the operations of the UNIX file
1021 system. This section discusses some of the implementation-specific
1024 \&Server/Client Relationship
1025 .IX NFS "server/client relationship"
1027 The NFS protocol is designed to allow servers to be as simple and
1028 general as possible. Sometimes the simplicity of the server can be a
1029 problem, if the client wants to implement complicated filesystem
1032 For example, some operating systems allow removal of open files. A
1033 process can open a file and, while it is open, remove it from the
1034 directory. The file can be read and written as long as the process
1035 keeps it open, even though the file has no name in the filesystem.
1036 It is impossible for a stateless server to implement these semantics.
1037 The client can do some tricks such as renaming the file on remove,
1038 and only removing it on close. We believe that the server provides
1039 enough functionality to implement most file system semantics on the
1042 Every NFS client can also potentially be a server, and remote and
1043 local mounted filesystems can be freely intermixed. This leads to
1044 some interesting problems when a client travels down the directory
1045 tree of a remote filesystem and reaches the mount point on the server
1046 for another remote filesystem. Allowing the server to follow the
1047 second remote mount would require loop detection, server lookup, and
1048 user revalidation. Instead, we decided not to let clients cross a
1049 server's mount point. When a client does a LOOKUP on a directory on
1050 which the server has mounted a filesystem, the client sees the
1051 underlying directory instead of the mounted directory. A client can
1052 do remote mounts that match the server's mount points to maintain the
1056 \&Pathname Interpretation
1057 .IX NFS "pathname interpretation"
1059 There are a few complications to the rule that pathnames are always
1060 parsed on the client. For example, symbolic links could have
1061 different interpretations on different clients. Another common
1062 problem for non-UNIX implementations is the special interpretation of
1063 the pathname ".." to mean the parent of a given directory. The next
1064 revision of the protocol uses an explicit flag to indicate the parent
1068 .IX NFS "permission issues"
1070 The NFS protocol, strictly speaking, does not define the permission
1071 checking used by servers. However, it is expected that a server
1072 will do normal operating system permission checking using
1074 style authentication as the basis of its protection mechanism. The
1075 server gets the client's effective "uid", effective "gid", and groups
1076 on each call and uses them to check permission. There are various
1077 problems with this method that can been resolved in interesting ways.
1079 Using "uid" and "gid" implies that the client and server share the
1080 same "uid" list. Every server and client pair must have the same
1081 mapping from user to "uid" and from group to "gid". Since every
1082 client can also be a server, this tends to imply that the whole
1083 network shares the same "uid/gid" space.
1086 revision of the NFS protocol) uses string names instead of numbers,
1087 but there are still complex problems to be solved.
1089 Another problem arises due to the usually stateful open operation.
1090 Most operating systems check permission at open time, and then check
1091 that the file is open on each read and write request. With stateless
1092 servers, the server has no idea that the file is open and must do
1093 permission checking on each read and write call. On a local
1094 filesystem, a user can open a file and then change the permissions so
1095 that no one is allowed to touch it, but will still be able to write
1096 to the file because it is open. On a remote filesystem, by contrast,
1097 the write would fail. To get around this problem, the server's
1098 permission checking algorithm should allow the owner of a file to
1099 access it regardless of the permission setting.
1101 A similar problem has to do with paging in from a file over the
1102 network. The operating system usually checks for execute permission
1103 before opening a file for demand paging, and then reads blocks from
1104 the open file. The file may not have read permission, but after it
1105 is opened it doesn't matter. An NFS server can not tell the
1106 difference between a normal file read and a demand page-in read. To
1107 make this work, the server allows reading of files if the "uid" given
1108 in the call has execute or read permission on the file.
1110 In most operating systems, a particular user (on the user ID zero)
1111 has access to all files no matter what permission and ownership they
1112 have. This "super-user" permission may not be allowed on the server,
1113 since anyone who can become super-user on their workstation could
1114 gain access to all remote files. The UNIX server by default maps
1115 user id 0 to -2 before doing its access checking. This works except
1116 for NFS root filesystems, where super-user access cannot be avoided.
1118 \&Setting RPC Parameters
1119 .IX NFS "setting RPC parameters"
1121 Various file system parameters and options should be set at mount
1122 time. The mount protocol is described in the appendix below. For
1123 example, "Soft" mounts as well as "Hard" mounts are usually both
1124 provided. Soft mounted file systems return errors when RPC
1125 operations fail (after a given number of optional retransmissions),
1126 while hard mounted file systems continue to retransmit forever.
1127 Clients and servers may need to keep caches of recent operations to
1128 help avoid problems with non-idempotent operations.
1130 \&Mount Protocol Definition
1131 .IX "mount protocol" "" "" "" PAGE MAJOR
1135 .IX "mount protocol" introduction
1137 The mount protocol is separate from, but related to, the NFS
1138 protocol. It provides operating system specific services to get the
1139 NFS off the ground -- looking up server path names, validating user
1140 identity, and checking access permissions. Clients use the mount
1141 protocol to get the first file handle, which allows them entry into a
1144 The mount protocol is kept separate from the NFS protocol to make it
1145 easy to plug in new access checking and validation methods without
1146 changing the NFS server protocol.
1148 Notice that the protocol definition implies stateful servers because
1149 the server maintains a list of client's mount requests. The mount
1150 list information is not critical for the correct functioning of
1151 either the client or the server. It is intended for advisory use
1152 only, for example, to warn possible clients when a server is going
1155 Version one of the mount protocol is used with version two of the NFS
1156 protocol. The only connecting point is the
1158 structure, which is the same for both protocols.
1161 .IX "mount protocol" "RPC information"
1162 .IP \fIAuthentication\fP
1163 The mount service uses
1167 style authentication only.
1168 .IP "\fITransport Protocols\fP"
1169 The mount service is currently supported on UDP/IP only.
1170 .IP "\fIPort Number\fP"
1171 Consult the server's portmapper, described in the chapter
1172 .I "Remote Procedure Calls: Protocol Specification",
1173 to find the port number on which the mount service is registered.
1175 \&Sizes of XDR Structures
1176 .IX "mount protocol" "XDR structure sizes"
1178 These are the sizes, given in decimal bytes, of various XDR
1179 structures used in the protocol:
1181 /* \fIThe maximum number of bytes in a pathname argument\fP */
1182 const MNTPATHLEN = 1024;
1184 /* \fIThe maximum number of bytes in a name argument\fP */
1185 const MNTNAMLEN = 255;
1187 /* \fIThe size in bytes of the opaque file handle\fP */
1192 .IX "mount protocol" "basic data types"
1193 .IX "mount data types"
1195 This section presents the data types used by the mount protocol.
1196 In many cases they are similar to the types used in NFS.
1200 .IX "mount data types" fhandle "" \fIfhandle\fP
1202 typedef opaque fhandle[FHSIZE];
1207 is the file handle that the server passes to the
1208 client. All file operations are done using file handles to refer
1209 to a file or directory. The file handle can contain whatever
1210 information the server needs to distinguish an individual file.
1212 This is the same as the "fhandle" XDR definition in version 2 of
1213 the NFS protocol; see
1214 .I "Basic Data Types"
1215 in the definition of the NFS protocol, above.
1219 .IX "mount data types" fhstatus "" \fIfhstatus\fP
1221 union fhstatus switch (unsigned status) {
1231 is a union. If a "status" of zero is returned,
1232 the call completed successfully, and a file handle for the
1233 "directory" follows. A non-zero status indicates some sort of
1234 error. In this case the status is a UNIX error number.
1238 .IX "mount data types" dirpath "" \fIdirpath\fP
1240 typedef string dirpath<MNTPATHLEN>;
1245 is a server pathname of a directory.
1249 .IX "mount data types" name "" \fIname\fP
1251 typedef string name<MNTNAMLEN>;
1256 is an arbitrary string used for various names.
1259 .IX "mount server procedures"
1261 The following sections define the RPC procedures supplied by a
1267 * Protocol description for the mount program
1274 * Version 1 of the mount protocol used with
1275 * version 2 of the NFS protocol.
1279 void MOUNTPROC_NULL(void) = 0;
1280 fhstatus MOUNTPROC_MNT(dirpath) = 1;
1281 mountlist MOUNTPROC_DUMP(void) = 2;
1282 void MOUNTPROC_UMNT(dirpath) = 3;
1283 void MOUNTPROC_UMNTALL(void) = 4;
1284 exportlist MOUNTPROC_EXPORT(void) = 5;
1291 .IX "mount server procedures" MNTPROC_NULL() "" \fIMNTPROC_NULL()\fP
1294 MNTPROC_NULL(void) = 0;
1297 This procedure does no work. It is made available in all RPC
1298 services to allow server response testing and timing.
1302 .IX "mount server procedures" MNTPROC_MNT() "" \fIMNTPROC_MNT()\fP
1305 MNTPROC_MNT(dirpath) = 1;
1308 If the reply "status" is 0, then the reply "directory" contains the
1309 file handle for the directory "dirname". This file handle may be
1310 used in the NFS protocol. This procedure also adds a new entry to
1311 the mount list for this client mounting "dirname".
1314 \&Return Mount Entries
1315 .IX "mount server procedures" MNTPROC_DUMP() "" \fIMNTPROC_DUMP()\fP
1320 mountlist nextentry;
1324 MNTPROC_DUMP(void) = 2;
1327 Returns the list of remote mounted filesystems. The "mountlist"
1328 contains one entry for each "hostname" and "directory" pair.
1331 \&Remove Mount Entry
1332 .IX "mount server procedures" MNTPROC_UMNT() "" \fIMNTPROC_UMNT()\fP
1335 MNTPROC_UMNT(dirpath) = 3;
1338 Removes the mount list entry for the input "dirpath".
1341 \&Remove All Mount Entries
1342 .IX "mount server procedures" MNTPROC_UMNTALL() "" \fIMNTPROC_UMNTALL()\fP
1345 MNTPROC_UMNTALL(void) = 4;
1348 Removes all of the mount list entries for this client.
1351 \&Return Export List
1352 .IX "mount server procedures" MNTPROC_EXPORT() "" \fIMNTPROC_EXPORT()\fP
1359 struct *exportlist {
1366 MNTPROC_EXPORT(void) = 5;
1369 Returns a variable number of export list entries. Each entry
1370 contains a filesystem name and a list of groups that are allowed to
1371 import it. The filesystem name is in "filesys", and the group name
1372 is in the list "groups".
1374 Note: The exportlist should contain
1375 more information about the status of the filesystem, such as a
projects / dragonfly.git / blob