nfs.rfc.ms

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

\&Read From Directory
.IX "NFS server procedures" NFSPROC_READDIR() "" \fINFSPROC_READDIR()\fP
.DS
struct readdirargs {
	fhandle dir;            
	nfscookie cookie;
	unsigned count;         
};

struct entry {
	unsigned fileid;
	filename name;
	nfscookie cookie;
	entry *nextentry;
};

union readdirres switch (stat status) {
	case NFS_OK:
		struct {
			entry *entries;
			bool eof;
		} readdirok;
	default:
		void;
};

readdirres
NFSPROC_READDIR (readdirargs) = 16;
.DE
.KE
Returns a variable number of  directory entries,  with a total size
of up to "count" bytes, from the directory given  by "dir".  If the
returned  value of "status"  is 
.I NFS_OK ,
then  it  is followed  by a
variable  number  of "entry"s.    Each "entry" contains  a "fileid"
which consists of a  unique number  to identify the  file within  a
filesystem,  the  "name" of the  file, and a "cookie" which   is an
opaque pointer to the next entry in  the  directory.  The cookie is
used  in the next  
.I READDIR 
call to get more  entries  starting at a
given point in  the directory.  The  special cookie zero (all  bits
zero) can be used to get the entries starting  at the  beginning of
the directory.  The "fileid" field should be the same number as the
"fileid" in the the  attributes of the  file.  (See the
.I "Basic Data Types"
section.) 
The "eof" flag has a value of
.I TRUE 
if there are no more entries in the directory.
.KS
.NH 3
\&Get Filesystem Attributes
.IX "NFS server procedures" NFSPROC_STATFS() "" \fINFSPROC_STATFS()\fP
.DS
union statfsres (stat status) {
	case NFS_OK:
		struct {
			unsigned tsize; 
			unsigned bsize; 
			unsigned blocks;
			unsigned bfree; 
			unsigned bavail;
		} info;
	default:
		void;
};

statfsres
NFSPROC_STATFS(fhandle) = 17;
.DE
.KE
If the  reply "status"  is 
.I NFS_OK ,
then the  reply "info" gives the
attributes for the filesystem that contains file referred to by the
input fhandle.  The attribute fields contain the following values:
.IP tsize:   
The optimum transfer size of the server in bytes.  This is
the number  of bytes the server  would like to have in the
data part of READ and WRITE requests.
.IP bsize:   
The block size in bytes of the filesystem.
.IP blocks:  
The total number of "bsize" blocks on the filesystem.
.IP bfree:   
The number of free "bsize" blocks on the filesystem.
.IP bavail:  
The number of  "bsize" blocks  available to non-privileged users.
.LP
Note: This call does not  work well if a  filesystem has  variable
size blocks.
.NH 1
\&NFS Implementation Issues
.IX NFS implementation
.LP
The NFS protocol is designed to be operating system independent, but
since this version was designed in a UNIX environment, many
operations have semantics similar to the operations of the UNIX file
system.  This section discusses some of the implementation-specific
semantic issues.
.NH 2
\&Server/Client Relationship
.IX NFS "server/client relationship"
.LP
The NFS protocol is designed to allow servers to be as simple and
general as possible.  Sometimes the simplicity of the server can be a
problem, if the client wants to implement complicated filesystem
semantics.
.LP
For example, some operating systems allow removal of open files.  A
process can open a file and, while it is open, remove it from the
directory.  The file can be read and written as long as the process
keeps it open, even though the file has no name in the filesystem.
It is impossible for a stateless server to implement these semantics.
The client can do some tricks such as renaming the file on remove,
and only removing it on close.  We believe that the server provides
enough functionality to implement most file system semantics on the
client.
.LP
Every NFS client can also potentially be a server, and remote and
local mounted filesystems can be freely intermixed.  This leads to
some interesting problems when a client travels down the directory
tree of a remote filesystem and reaches the mount point on the server
for another remote filesystem.  Allowing the server to follow the
second remote mount would require loop detection, server lookup, and
user revalidation.  Instead, we decided not to let clients cross a
server's mount point.  When a client does a LOOKUP on a directory on
which the server has mounted a filesystem, the client sees the
underlying directory instead of the mounted directory.  A client can
do remote mounts that match the server's mount points to maintain the
server's view.
.LP
.NH 2
\&Pathname Interpretation
.IX NFS "pathname interpretation"
.LP
There are a few complications to the rule that pathnames are always
parsed on the client.  For example, symbolic links could have
different interpretations on different clients.  Another common
problem for non-UNIX implementations is the special interpretation of
the pathname ".."  to mean the parent of a given directory.  The next
revision of the protocol uses an explicit flag to indicate the parent
instead.
.NH 2
\&Permission Issues
.IX NFS "permission issues"
.LP
The NFS protocol, strictly speaking, does not define the permission
checking used  by servers.  However,  it is  expected that a server
will do normal operating system permission checking using 
.I AUTH_UNIX 
style authentication as the basis of its protection mechanism.  The
server gets the client's effective "uid", effective "gid", and groups
on each call and uses them to check permission.  There are various
problems with this method that can been resolved in interesting ways.
.LP
Using "uid" and "gid" implies that the client and server share the
same "uid" list.  Every server and client pair must have the same
mapping from user to "uid" and from group to "gid".  Since every
client can also be a server, this tends to imply that the whole
network shares the same "uid/gid" space.
.I AUTH_DES 
(and the  next
revision of the NFS protocol) uses string names instead of numbers,
but there are still complex problems to be solved.
.LP
Another problem arises due to the usually stateful open operation.
Most operating systems check permission at open time, and then check
that the file is open on each read and write request.  With stateless
servers, the server has no idea that the file is open and must do
permission checking on each read and write call.  On a local
filesystem, a user can open a file and then change the permissions so
that no one is allowed to touch it, but will still be able to write
to the file because it is open.  On a remote filesystem, by contrast,
the write would fail.  To get around this problem, the server's
permission checking algorithm should allow the owner of a file to
access it regardless of the permission setting.
.LP
A similar problem has to do with paging in from a file over the
network.  The operating system usually checks for execute permission
before opening a file for demand paging, and then reads blocks from
the open file.  The file may not have read permission, but after it
is opened it doesn't matter.  An NFS server can not tell the
difference between a normal file read and a demand page-in read.  To
make this work, the server allows reading of files if the "uid" given
in the call has execute or read permission on the file.
.LP
In most operating systems, a particular user (on the user ID zero)
has access to all files no matter what permission and ownership they
have.  This "super-user" permission may not be allowed on the server,
since anyone who can become super-user on their workstation could
gain access to all remote files.  The UNIX server by default maps
user id 0 to -2 before doing its access checking.  This works except
for NFS root filesystems, where super-user access cannot be avoided.
.NH 2
\&Setting RPC Parameters
.IX NFS "setting RPC parameters"
.LP
Various file system parameters and options should be set at mount
time.  The mount protocol is described in the appendix below.  For
example, "Soft" mounts as well as "Hard" mounts are usually both
provided.  Soft mounted file systems return errors when RPC
operations fail (after a given number of optional retransmissions),
while hard mounted file systems continue to retransmit forever.
Clients and servers may need to keep caches of recent operations to
help avoid problems with non-idempotent operations.
.NH 1
\&Mount Protocol Definition
.IX "mount protocol" "" "" "" PAGE MAJOR
.sp 1
.NH 2
\&Introduction
.IX "mount protocol" introduction
.LP
The mount protocol is separate from, but related to, the NFS
protocol.  It provides operating system specific services to get the
NFS off the ground -- looking up server path names, validating user
identity, and checking access permissions.  Clients use the mount
protocol to get the first file handle, which allows them entry into a
remote filesystem.
.LP
The mount protocol is kept separate from the NFS protocol to make it
easy to plug in new access checking and validation methods without
changing the NFS server protocol.
.LP
Notice that the protocol definition implies stateful servers because
the server maintains a list of client's mount requests.  The mount
list information is not critical for the correct functioning of
either the client or the server.  It is intended for advisory use
only, for example, to warn possible clients when a server is going
down.
.LP
Version one of the mount protocol is used with version two of the NFS
protocol.  The only connecting point is the
.I fhandle 
structure, which is the same for both protocols.
.NH 2
\&RPC Information
.IX "mount protocol"  "RPC information"
.IP \fIAuthentication\fP
The mount service uses 
.I AUTH_UNIX 
and 
.I AUTH_DES 
style authentication only.
.IP "\fITransport Protocols\fP"
The mount service is currently supported on UDP/IP only.
.IP "\fIPort Number\fP"
Consult the server's portmapper, described in the chapter
.I "Remote Procedure Calls: Protocol Specification",
to  find  the  port number on which the mount service is registered.
.NH 2
\&Sizes of XDR Structures
.IX "mount protocol" "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 in a pathname argument\fP */
const MNTPATHLEN = 1024;

/* \fIThe maximum number of bytes in a name argument\fP */
const MNTNAMLEN = 255;

/* \fIThe size in bytes of the opaque file handle\fP */
const FHSIZE = 32;
.DE
.NH 2
\&Basic Data Types
.IX "mount protocol" "basic data types"
.IX "mount data types"
.LP
This section presents the data  types used by  the  mount protocol.
In many cases they are similar to the types used in NFS.
.KS
.NH 3
\&fhandle
.IX "mount data types" fhandle "" \fIfhandle\fP
.DS
typedef opaque fhandle[FHSIZE];
.DE
.KE
The type 
.I fhandle 
is the file handle that the server passes to the
client.  All file operations are done  using file handles  to refer
to a  file  or directory.   The  file handle  can  contain whatever
information the server needs to distinguish an individual file.
.LP
This  is the  same as the "fhandle" XDR definition in version 2 of
the NFS protocol;  see 
.I "Basic Data Types"
in the definition of the NFS protocol, above.
.KS
.NH 3
\&fhstatus
.IX "mount data types" fhstatus "" \fIfhstatus\fP
.DS
union fhstatus switch (unsigned status) {
	case 0:
		fhandle directory;
	default:
		void;
};
.DE
.KE
The type 
.I fhstatus 
is a union.  If a "status" of zero is returned,
the  call completed   successfully, and  a  file handle   for   the
"directory"  follows.  A  non-zero  status indicates  some  sort of
error.  In this case the status is a UNIX error number.
.KS
.NH 3
\&dirpath
.IX "mount data types" dirpath "" \fIdirpath\fP
.DS
typedef string dirpath<MNTPATHLEN>;
.DE
.KE
The type 
.I dirpath 
is a server pathname of a directory.
.KS
.NH 3
\&name
.IX "mount data types" name "" \fIname\fP
.DS
typedef string name<MNTNAMLEN>;
.DE
.KE
The type 
.I name 
is an arbitrary string used for various names.
.NH 2
\&Server Procedures
.IX "mount server procedures"
.LP
The following sections define the RPC procedures  supplied by a
mount server.
.ie t .DS
.el .DS L
.ft I
/*
* Protocol description for the mount program
*/
.ft CW

program MOUNTPROG {
.ft I
/*
* Version 1 of the mount protocol used with
* version 2 of the NFS protocol.
*/
.ft CW
	version MOUNTVERS {
		void        MOUNTPROC_NULL(void)    = 0;
		fhstatus    MOUNTPROC_MNT(dirpath)  = 1;
		mountlist   MOUNTPROC_DUMP(void)    = 2;
		void        MOUNTPROC_UMNT(dirpath) = 3;
		void        MOUNTPROC_UMNTALL(void) = 4;
		exportlist  MOUNTPROC_EXPORT(void)  = 5;
	} = 1;
} = 100005;
.DE
.KS
.NH 3
\&Do Nothing
.IX "mount server procedures" MNTPROC_NULL() "" \fIMNTPROC_NULL()\fP
.DS
void 
MNTPROC_NULL(void) = 0;
.DE
.KE
This  procedure does no work.  It   is  made  available in all  RPC
services to allow server response testing and timing.
.KS
.NH 3
\&Add Mount Entry
.IX "mount server procedures" MNTPROC_MNT() "" \fIMNTPROC_MNT()\fP
.DS
fhstatus
MNTPROC_MNT(dirpath) = 1;
.DE
.KE
If the reply "status" is 0, then the reply "directory" contains the
file handle for the directory "dirname".  This file handle may be
used in the NFS protocol.  This procedure also adds a new entry to
the mount list for this client mounting "dirname".
.KS
.NH 3
\&Return Mount Entries
.IX "mount server procedures" MNTPROC_DUMP() "" \fIMNTPROC_DUMP()\fP
.DS
struct *mountlist {
	name      hostname;
	dirpath   directory;
	mountlist nextentry;
};

mountlist
MNTPROC_DUMP(void) = 2;
.DE
.KE
Returns  the list of  remote mounted filesystems.   The "mountlist"
contains one entry for each "hostname" and "directory" pair.
.KS
.NH 3
\&Remove Mount Entry
.IX "mount server procedures" MNTPROC_UMNT() "" \fIMNTPROC_UMNT()\fP
.DS
void
MNTPROC_UMNT(dirpath) = 3;
.DE
.KE
Removes the mount list entry for the input "dirpath".
.KS
.NH 3
\&Remove All Mount Entries
.IX "mount server procedures" MNTPROC_UMNTALL() "" \fIMNTPROC_UMNTALL()\fP
.DS
void
MNTPROC_UMNTALL(void) = 4;
.DE
.KE
Removes all of the mount list entries for this client.
.KS
.NH 3
\&Return Export List
.IX "mount server procedures" MNTPROC_EXPORT() "" \fIMNTPROC_EXPORT()\fP
.DS
struct *groups {
	name grname;
	groups grnext;
};

struct *exportlist {
	dirpath filesys;
	groups groups;
	exportlist next;
};

exportlist
MNTPROC_EXPORT(void) = 5;
.DE
.KE
Returns a variable number of export list entries.  Each entry
contains a filesystem name and a list of groups that are allowed to
import it.  The filesystem name is in "filesys", and the group name
is in the list "groups".
.LP
Note:  The exportlist should contain
more information about the status of the filesystem, such as a
read-only flag.