nfs.rfc.ms

RTEMS (Real-Time Executive for Multiprocessor Systems) is a free open source real-time operating sys

.\"
.\" 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
.LP
Note: 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
.LP
The 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).  Implementations
exist for a variety of machines, from personal computers to
supercomputers.
.LP
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.
.NH 2
\&Remote Procedure Call
.IX "Remote Procedure Call"
.LP
Sun's remote procedure call specification provides a procedure-
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 specific protocols, so it can be used with
any underlying transport protocol.  See the
.I "Remote Procedure Calls: Protocol Specification"
chapter of this manual.
.NH 2
\&External Data Representation
.IX "External Data Representation"
.LP
The External Data Representation (XDR) standard provides a common
way of representing a set of data types over a network.  
The NFS
Protocol Specification is written using the RPC data description
language.  
For more information, see the
.I " External Data Representation Standard: Protocol Specification."  
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 implementations
of NFS.
.NH 2
\&Stateless Servers
.IX "stateless servers"
.IX servers stateless
.LP
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.
.LP
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.
.LP
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).
.NH 1
\&NFS Protocol Definition
.IX NFS "protocol definition"
.IX NFS protocol
.LP
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.
.NH 2
\&File System Model
.IX filesystem model
.LP
NFS assumes a file system that is hierarchical, with directories 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.
.LP
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 components, and different operating
systems use different separators.  We could define a Network Standard
Pathname Representation, but then every pathname would have to be
parsed and converted at each end.  Other issues are discussed in
\fINFS Implementation Issues\fP below.
.LP
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 representing 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.
.NH 2
\&RPC Information
.IX NFS "RPC information"
.IP \fIAuthentication\fP
The   NFS  service uses 
.I AUTH_UNIX ,
.I AUTH_DES ,
or 
.I AUTH_SHORT 
style
authentication, 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 is
not an officially assigned port, so  later versions of the protocol
use the \*QPortmapping\*U facility of RPC.
.NH 2
\&Sizes of XDR Structures
.IX "XDR structure sizes"
.LP
These are the sizes, given in decimal bytes, of various XDR
structures 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"
.LP
The following XDR  definitions are basic  structures and types used
in other structures described further on.
.KS
.NH 3
\&stat
.IX "NFS data types" stat "" \fIstat\fP
.DS
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
};
.DE
.KE
.LP
The 
.I stat 
type  is returned with every  procedure's  results.   A
value of 
.I NFS_OK 
indicates that the  call completed successfully 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.
.IP \fBNFSERR_PERM\fP:
Not owner.  The caller does not have correct ownership
to perform the requested operation.
.IP \fBNFSERR_NOENT\fP:
No such file or directory.    The file or directory
specified does not exist.
.IP \fBNFSERR_IO\fP:
Some sort of hard  error occurred when the operation was
in 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 the
correct 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   a
non-directory in a directory operation.
.IP \fBNFSERR_ISDIR\fP:
Is a directory.  The caller specified  a directory in
a non- directory operation.
.IP \fBNFSERR_FBIG\fP:
File too large.   The  operation caused a file to grow
beyond the server's limit.
.IP \fBNFSERR_NOSPC\fP:
No space left on  device.   The operation caused the
server'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  a
directory that was not empty.
.IP \fBNFSERR_DQUOT\fP:
Disk quota exceeded.  The client's disk  quota on the
server 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
.DS
enum ftype {
	NFNON = 0,
	NFREG = 1,
	NFDIR = 2,
	NFBLK = 3,
	NFCHR = 4,
	NFLNK = 5
};
.DE
.KE
The 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
.DS
typedef opaque fhandle[FHSIZE];
.DE
.KE
The
.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 server
needs to distinguish an individual file.
.KS
.NH 3
\&timeval
.IX "NFS data types" timeval "" \fItimeval\fP
.DS
struct timeval {
	unsigned int seconds;
	unsigned int useconds;
};
.DE
.KE
The 
.I timeval
structure 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
.DS
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;
};
.DE
.KE
The
.I fattr 
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
.I NFCHR 
or
.I NFBLK ;
"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.
.LP
"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.
.TS
box tab (&) ;
cfI cfI
lfL 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
.KS
Notes:
.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 in
the mode  bits  and in  the file type.   This   is fixed  in future
versions.
.IP
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.
.KE
.LP
.KS
.NH 3
\&sattr
.IX "NFS data types" sattr "" \fIsattr\fP
.DS
struct sattr {
	unsigned int mode;
	unsigned int uid;
	unsigned int gid;
	unsigned int size;
	timeval      atime;
	timeval      mtime;
};
.DE
.KE
The 
.I sattr
structure contains the file attributes which can be set
from 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
.DS
typedef string filename<MAXNAMLEN>;
.DE
.KE