.\".\" Must use  --  tbl  --  with this one.\".\" @(#)nfs.rfc.ms	2.2 88/08/05 4.0 RPCSRC.de BT.if \\n%=1 .tl ''- % -''...ND.\" prevent excess underlining in nroff.if n .fp 2 R.OH 'Network File System: Version 2 Protocol Specification''Page %'.EH 'Page %''Network File System: Version 2 Protocol Specification'.if \\n%=1 .bp.SH\&Network File System: Version 2 Protocol Specification.IX NFS "" "" "" PAGE MAJOR.IX "Network File System" "" "" "" PAGE MAJOR.IX NFS "version-2 protocol specification".IX "Network File System" "version-2 protocol specification".LP.NH 0\&Status of this Standard.LPNote: This document specifies a protocol that Sun Microsystems, Inc.,and others are using.  It specifies it in standard ARPA RFC form..NH 1\&Introduction.IX NFS introduction.LPThe Sun Network Filesystem (NFS) protocol provides transparent remote access to shared filesystems over local area networks.  The NFS protocol is designed to be machine, operating system, network architecture, and transport protocol independent.  This independence is achieved through the use of Remote Procedure Call (RPC) primitives built on top of an External Data Representation (XDR).  Implementationsexist for a variety of machines, from personal computers tosupercomputers..LPThe supporting mount protocol allows the server to hand out remoteaccess privileges to a restricted set of clients.  It performs theoperating system-specific functions that allow, for example, toattach remote directory trees to some local file system..NH 2\&Remote Procedure Call.IX "Remote Procedure Call".LPSun's remote procedure call specification provides a procedure-oriented interface to remote services.  Each server supplies aprogram that is a set of procedures.  NFS is one such "program".The combination of host address, program number, and procedurenumber specifies one remote service procedure.  RPC does not dependon services provided by specific protocols, so it can be used withany underlying transport protocol.  See the.I "Remote Procedure Calls: Protocol Specification"chapter of this manual..NH 2\&External Data Representation.IX "External Data Representation".LPThe External Data Representation (XDR) standard provides a commonway of representing a set of data types over a network.  The NFSProtocol Specification is written using the RPC data descriptionlanguage.  For more information, see the.I " External Data Representation Standard: Protocol Specification."  Sun provides implementations of XDR andRPC,  but NFS does not require their use.  Any software thatprovides equivalent functionality can be used, and if the encodingis exactly the same it can interoperate with other implementationsof NFS..NH 2\&Stateless Servers.IX "stateless servers".IX servers stateless.LPThe NFS protocol is stateless.  That is, a server does not need tomaintain any extra state information about any of its clients inorder to function correctly.  Stateless servers have a distinctadvantage over stateful servers in the event of a failure.  Withstateless servers, a client need only retry a request until theserver responds; it does not even need to know that the server hascrashed, or the network temporarily went down.  The client of astateful server, on the other hand, needs to either detect a servercrash and rebuild the server's state when it comes back up, orcause client operations to fail..LPThis may not sound like an important issue, but it affects theprotocol in some unexpected ways.  We feel that it is worth a bitof extra complexity in the protocol to be able to write very simpleservers that do not require fancy crash recovery..LPOn the other hand, NFS deals with objects such as files anddirectories that inherently have state -- what good would a file beif it did not keep its contents intact?  The goal is to notintroduce any extra state in the protocol itself.  Another way tosimplify recovery is by making operations "idempotent" wheneverpossible (so that they can potentially be repeated)..NH 1\&NFS Protocol Definition.IX NFS "protocol definition".IX NFS protocol.LPServers have been known to change over time, and so can theprotocol that they use. So RPC provides a version number with eachRPC request. This RFC describes version two of the NFS protocol.Even in the second version, there are various obsolete proceduresand parameters, which will be removed in later versions. An RFCfor version three of the NFS protocol is currently underpreparation..NH 2\&File System Model.IX filesystem model.LPNFS assumes a file system that is hierarchical, with directories asall but the bottom-level files.  Each entry in a directory (file,directory, device, etc.)  has a string name.  Different operatingsystems may have restrictions on the depth of the tree or the namesused, as well as using different syntax to represent the "pathname",which is the concatenation of all the "components" (directory andfile names) in the name.  A "file system" is a tree on a singleserver (usually a single disk or physical partition) with a specified"root".  Some operating systems provide a "mount" operation to makeall file systems appear as a single tree, while others maintain a"forest" of file systems.  Files are unstructured streams ofuninterpreted bytes.  Version 3 of NFS uses a slightly more generalfile system model..LPNFS looks up one component of a pathname at a time.  It may not beobvious why it does not just take the whole pathname, traipse downthe directories, and return a file handle when it is done.  There areseveral good reasons not to do this.  First, pathnames needseparators between the directory components, and different operatingsystems use different separators.  We could define a Network StandardPathname Representation, but then every pathname would have to beparsed and converted at each end.  Other issues are discussed in\fINFS Implementation Issues\fP below..LPAlthough files and directories are similar objects in many ways,different procedures are used to read directories and files.  Thisprovides a network standard format for representing directories.  Thesame argument as above could have been used to justify a procedurethat returns only one directory entry per call.  The problem isefficiency.  Directories can contain many entries, and a remote callto return each would be just too slow..NH 2\&RPC Information.IX NFS "RPC information".IP \fIAuthentication\fPThe   NFS  service uses .I AUTH_UNIX ,.I AUTH_DES ,or .I AUTH_SHORT styleauthentication, except in  the  NULL procedure where   .I AUTH_NONE is also allowed..IP "\fITransport Protocols\fP"NFS currently is supported on UDP/IP only.  .IP "\fIPort Number\fP"The NFS protocol currently uses the UDP port number 2049.  This isnot an officially assigned port, so  later versions of the protocoluse the \*QPortmapping\*U facility of RPC..NH 2\&Sizes of XDR Structures.IX "XDR structure sizes".LPThese are the sizes, given in decimal bytes, of various XDRstructures used in the protocol:.DS/* \fIThe maximum number of bytes of data in a READ or WRITE request\fP  */const MAXDATA = 8192;/* \fIThe maximum number of bytes in a pathname argument\fP */const MAXPATHLEN = 1024;/* \fIThe maximum number of bytes in a file name argument\fP */const MAXNAMLEN = 255;/* \fIThe size in bytes of the opaque "cookie" passed by READDIR\fP */const COOKIESIZE  = 4;/* \fIThe size in bytes of the opaque file handle\fP */const FHSIZE = 32;.DE.NH 2\&Basic Data Types.IX "NFS data types".IX NFS "basic data types".LPThe following XDR  definitions are basic  structures and types usedin other structures described further on..KS.NH 3\&stat.IX "NFS data types" stat "" \fIstat\fP.DSenum 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};.DE.KE.LPThe .I stat type  is returned with every  procedure's  results.   Avalue of .I NFS_OK indicates that the  call completed successfully andthe  results are  valid.  The  other  values indicate  some kind oferror  occurred on the  server  side  during the servicing   of theprocedure.  The error values are derived from UNIX error numbers..IP \fBNFSERR_PERM\fP:Not owner.  The caller does not have correct ownershipto perform the requested operation..IP \fBNFSERR_NOENT\fP:No such file or directory.    The file or directoryspecified does not exist..IP \fBNFSERR_IO\fP:Some sort of hard  error occurred when the operation wasin progress.  This could be a disk error, for example..IP \fBNFSERR_NXIO\fP:No such device or address..IP \fBNFSERR_ACCES\fP:Permission  denied.  The  caller does  not  have thecorrect permission to perform the requested operation..IP \fBNFSERR_EXIST\fP:File exists.  The file specified already exists..IP \fBNFSERR_NODEV\fP:No such device..IP \fBNFSERR_NOTDIR\fP:Not   a  directory.    The  caller  specified   anon-directory in a directory operation..IP \fBNFSERR_ISDIR\fP:Is a directory.  The caller specified  a directory ina non- directory operation..IP \fBNFSERR_FBIG\fP:File too large.   The  operation caused a file to growbeyond the server's limit..IP \fBNFSERR_NOSPC\fP:No space left on  device.   The operation caused theserver's filesystem to reach its limit..IP \fBNFSERR_ROFS\fP:Read-only filesystem.  Write attempted on a read-only filesystem..IP \fBNFSERR_NAMETOOLONG\fP:File name   too   long.  The file  name  in  an operation was too long..IP \fBNFSERR_NOTEMPTY\fP:Directory   not empty.  Attempted  to   remove  adirectory that was not empty..IP \fBNFSERR_DQUOT\fP:Disk quota exceeded.  The client's disk  quota on theserver has been exceeded..IP \fBNFSERR_STALE\fP: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..IP \fBNFSERR_WFLUSH\fP:The server's  write cache  used  in the.I WRITECACHE call got flushed to disk..LP.KS.NH 3\&ftype.IX "NFS data types" ftype "" \fIftype\fP.DSenum ftype {	NFNON = 0,	NFREG = 1,	NFDIR = 2,	NFBLK = 3,	NFCHR = 4,	NFLNK = 5};.DE.KEThe enumeration.I ftype gives the type of a file.  The type .I NFNON indicates a non-file,.I NFREG is a regular file, .I NFDIR is a directory,.I NFBLK is a block-special device, .I NFCHR is a character-special device, and.I NFLNK is a symbolic link..KS.NH 3\&fhandle.IX "NFS data types" fhandle "" \fIfhandle\fP.DStypedef opaque fhandle[FHSIZE];.DE.KEThe.I fhandle 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 contain whatever information the serverneeds to distinguish an individual file..KS.NH 3\&timeval.IX "NFS data types" timeval "" \fItimeval\fP.DSstruct timeval {	unsigned int seconds;	unsigned int useconds;};.DE.KEThe .I timevalstructure is the number of seconds and microseconds since midnight January 1, 1970, Greenwich Mean Time.  It is used to pass time and date information..KS.NH 3\&fattr.IX "NFS data types" fattr "" \fIfattr\fP.DSstruct 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;};.DE.KEThe.I fattr structure contains the attributes of a file; "type" is the type ofthe file; "nlink" is the number of hard links to the file (the numberof different names for the same file); "uid" is the useridentification number of the owner of the file; "gid" is the groupidentification number of the group of the file; "size" is the size inbytes of the file; "blocksize" is the size in bytes of a block of thefile; "rdev" is the device number of the file if it is type.I NFCHR or.I NFBLK ;"blocks" is the number of blocks the file takes up on disk; "fsid" isthe file system identifier for the filesystem containing the file;"fileid" is a number that uniquely identifies the file within itsfilesystem; "atime" is the time when the file was last accessed foreither read or write; "mtime" is the time when the file data was lastmodified (written); and "ctime" is the time when the status of thefile was last changed.  Writing to the file also changes "ctime" ifthe size of the file changes..LP"mode" is the access mode encoded as a set of bits.  Notice that thefile 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 futureversions.  The descriptions given below specify the bit positionsusing octal numbers..TSbox tab (&) ;cfI cfIlfL l .Bit&Description_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..TE.KSNotes:.IP The bits are  the same as the mode   bits returned  by  the.I stat(2) system call in the UNIX system.  The file  type is  specified  both inthe mode  bits  and in  the file type.   This   is fixed  in futureversions..IPThe "rdev" field in the attributes structure is an operating systemspecific device specifier.  It  will be  removed and generalized inthe next revision of the protocol..KE.LP.KS.NH 3\&sattr.IX "NFS data types" sattr "" \fIsattr\fP.DSstruct sattr {	unsigned int mode;	unsigned int uid;	unsigned int gid;	unsigned int size;	timeval      atime;	timeval      mtime;};.DE.KEThe .I sattrstructure contains the file attributes which can be setfrom the client.  The fields are the same as for  .I fattr above.  A "size" of zero  means the file should be  truncated.A value of -1 indicates a field that should be ignored..LP.KS.NH 3\&filename.IX "NFS data types" filename "" \fIfilename\fP.DStypedef string filename<MAXNAMLEN>;.DE.KE