XNFS Service Model

Introduction

This chapter describes the the basic XNFS Service Model (XNFSSM). Its purpose is to provide a high-level description of the XNFSSM in terms of abstract objects and operations which are independent of any particular implementation.

The XNFSSM describes the way in which cooperating XNFS client and server systems interact in order to:

1. (on a server) Make a file system available for use by clients

2. (on a client) Gain access to a file system on a server and make it usable by local processes

3. (on a client) Access files and directories stored on a server

4. (on a client) Make a remote file system unusable by local processes and give up access to the file system

5. (on a server) Make a file system unavailable to clients

Before the formal elements of the XNFSSM are defined, an informal overview may be helpful.

Informal Overview of XNFS

This section provides a slightly simplified example of the use of XNFS to access remote files. File Hierarchy on Example System Called alpha illustrates a portion of the file hierarchy on an X/Open-compliant system with the system name alpha.

Users and applications on system alpha can refer to files within this hierarchy with pathnames such as /bin/cat and /usr1/geoff/fu.

Similarly, File Hierarchy on Example System Called beta illustrates part of the file hierarchy on the system beta.

The administrator of system beta decides to make the portion of the file system hierarchy under the directory /staff available to other systems within the network. This is accomplished by exporting the directory /staff.

The administrator of system alpha now decides to make this file system available to users and applications on alpha. This process is referred to as mounting the remote file system. To mount a file system, three pieces of information must be provided:

• The name of the system exporting the file system

• The name of the directory to be mounted

• The name of a directory within the local file system to be used as the mount point

The choice of mount point is important, since it determines the name by which the remote directory, and everything below it, will be known on the client system. In this case, the administrator chooses to mount /staff from system beta on the (empty) directory /mntdir. To a user of system alpha the local file system hierarchy now appears as shown in View from System alpha of Example File Hierarchy on System beta .

If a user types the command /bin/cat /mntdir/jan/first, the result is to list the contents of the file /staff/jan/first stored on the system beta. The command cd /mntdir/petr will select the directory /staff/petr on beta as the current directory; typing ls will show the file budget, and df . will display the amount of free space on the remote file system.

One effect of mounting a file system on a directory is that the contents of the local mount point directory become inaccessible while the mount is in effect. Since an empty directory is usually chosen as the mount point, this is not normally a problem. Suppose, however, that the local file system on alpha was as shown in Example 2 File Hierarchy on System Called alpha .

If the directory /staff on beta is mounted on /usr2, the resulting file system hierarchy will be as shown in Resulting File Hierarchy on System alpha from Example 2 .

Note that, for example, the file /usr2/jason/old is now inaccessible. Furthermore, the path /usr2/petr/budget is still valid, but it now refers to the file /staff/petr/budget on beta.

Elements of the XNFS Service Model

The XNFS Service Model incorporates the following elements:

• The ExportedFileSystem and MountedFileSystem objects

• The ExpFileSysOp and UnExpFileSysOp Administrative operations and their derivatives

• The ShowExpFileSysOp, MntFileSysOp and UnMntFileSysOp administrative operations and their derivatives

• File and directory access

The operations and objects are abstractions only. It is not expected that an XNFS implementation will incorporate procedures and data structures which correspond to these definitions. The (informal) definition of these attributes is not to be interpreted as implying a specific representation. The process of mounting a file relies on retrieving from the server a token (FileHandle) which corresponds to the remote file system, and storing an association of this token with the point in the local file system where the remote file system appears. This may be implemented in a variety of ways by using, for example, a command line utility, a graphical network resource browser, or "on the fly" using some kind of "automounter". However the notion of the FileHandle attribute of a mounted file system must be stored in some form.

XNFS Objects

ExportedFileSystem

An ExportedFileSystem object is created on an XNFS server as a result of a successful ExpFileSysOp operation. It is added to the set of exported file systems known to the mount server.

An XNFS server must implement the following set of ExportedFileSystem attributes, but is not precluded from adding others.

A WebNFS server must implement the following additional attribute:

A fuller description of each attribute follows.

PathName=pathname

This attribute identifies the file system object to be exported. This attribute must be specified.

Mode={ReadOnly or ReadWrite}

A value of ReadOnly specifies that the named file system object is not writable by XNFS clients. ReadWrite (the default) means that read and write access are granted.

AnonMapping=uid

Specifies the UID to be used for NFS accesses from an "unknown" user. Users with UID 0 are always considered unknown by the NFS server unless they are included in the Root attribute below. The recommended default value of this attribute is -2. Specifying AnonMapping=-1 disables anonymous access to the file system.

Root=hostname[:hostname]...

If this attribute is specified, NFS accesses from the specified systems with UID 0 are processed without being subject to the AnonMapping process. If this attribute is not specified, all UID 0 accesses are mapped.

Access={hostname or groupname}[:{hostname or groupname}]...

This attribute may be used to explicitly identify those systems which may have access to the file system. Each element in the associated list identifies a host, or a group of hosts, which is to be allowed to mount the file system. The mechanism whereby a hostname or groupname is resolved is not specified. If this attribute is not specified, the file system is accessible to any client system. Note that the access control provided by the Access attribute is applied only at the time that the client mounts the file system object; subsequent NFS accesses using the file handle acquired by the mount will not be affected by any changes to the Access list.

Public

A WebNFS server may designate a single ExportedFileSystem as the public file system. References to the public filehandle (see WebNFS Extensions ) are taken to mean the root of this file system. Alternatively, the server may designate a single directory in a non-exported file system. In this case, references to the public filehandle are taken to mean this directory. If the server designates a non-exported directory, clients must ensure that paths relative to the public filehandle refer to objects in an ExportedFileSystem.

MountedFileSystem

A MountedFileSystem object is created on an XNFS client as a result of a successful MntFileSysOp operation. The local mount point object is marked as remote, as discussed in File and Directory Operations .

An XNFS client must implement the following set of MountedFileSystem attributes, but is not precluded from adding others.

A fuller description of each attribute follows.

FileHandle

This attribute identifies the file system object on the server.

PathName=pathname

This attribute identifies the file system object to be mounted. This attribute must be specified.

Server=hostname

This attribute identifies the XNFS server system from which the object is to be mounted. This attribute must be specified.

MountPoint=pathname

This attribute identifies the local file system object on which the XNFS object is to be mounted. This attribute must be specified. The mountpoint must exist. Upon completion of the MntFileSysOp operation, the previous contents of the mountpoint will be inaccessible and the mountpoint pathname will refer to the XNFS mounted object. Note that if this object is a regular file rather than a directory the effects of directory-related operations are undefined.

Mode={ReadOnly or ReadWrite}

A value of ReadOnly specifies that the named file system object will be mounted for reading only. ReadWrite (the recommended default) means that writes will be allowed (although the server may reject them if the file system object was exported in ReadOnly mode).

GrpID={True or False}

If True, any file or directory created on the file system will inherit the group ID of the parent directory. If False, the group ID is set to the group of the current process or the parent directory, as specified by XSI. The recommend default is False.

SetUID={True or False}

If True, programs stored on the XNFS server which have the SetUID attribute may be executed with the corresponding effective UID. If false, such programs are executed with the current UID. The recommended default is False.

ReadSize=nn

When reading data from a remote file, the maximum amount of data that will be requested in a single RPC call is nn bytes. The recommended default value for this attribute is implementation-dependent. In addition, the XNFS client may limit the maximum transfer size to the info.tsize advertised by the server in the statfsres attributes (see Name ).

WriteSize=nn

When writing data to a remote file, the maximum amount of data that will be written in a single RPC call is nn bytes. The recommended default value for this attribute is implementation-dependent. In addition, the XNFS client may limit the maximum transfer size to the info.tsize advertised by the server in the statfsres attributes (see Name ).

NFSTimeOut=nn

Specifies that the initial timeout for an NFS RPC request is nn tenths of a second. (The timeout for subsequent retransmissions will depend on an implementation-dependent backoff algorithm.) The recommended default is 7, equivalent to a timeout of 700 milliseconds.

NFSRetransmissions=nn

If the RetrySemantics attribute is Soft, this specifies the number of times that an NFS RPC request will be retransmitted before the corresponding XSI request fails. The recommended default is 3.

RetrySemantics={Soft or Hard}

If a file system is mounted Hard (the recommended default), a failure of the server to respond to an NFS RPC causes the request to be retried until the server responds, or until the local process is interrupted (if Intr=True). If the file system is mounted with RetrySemantics=Soft, the corresponding XSI call will fail after the number of retries specified by NFSRetransmissions (see below).

Intr={True or False}

If True, a keyboard signal to a process will cause any operation which is being retried RetrySemantics=Hard to be abandoned.

NFSServerPort=nn

Specifies that NFS RPC requests are directed to UDP port nn on the server. The recommended default is 2049.

AttribCaching={True or False}

If True, no attribute, access, or directory caching will be performed. Otherwise the attributes (including permissions, size and timestamps) for files and directories may be cached to reduce the need to perform over-the-wire GETATTR or ACCESS RPCs. The ACRegMin, ACRegMax, ACDirMin and ACDirMax attributes control the length of time for which the cached values will be retained.

ACRegMin=nn

Hold cached attributes for at least nn seconds after file modification. The recommended default is 3.

ACRegMax=nn

Hold cached attributes for no more than nn seconds after file modification. The recommended default is 60.

ACDirMin=nn

Hold cached attributes for at least nn seconds after directory update. The recommended default is 30.

ACDirMax=nn

Hold cached attributes for no more than nn seconds after directory update. The recommended default is 60.

XNFS Server Operations

The four XNFS server administration operations are used to export or unexport local file system objects. All require appropriate privileges. These operations merely update the set of ExportedFileSystem objects; it is the responsibility of the mount server to interpret incoming MNTPROC_MNT requests and determine whether or not the request is to be granted (see The MntFileSysOp Operation ). The mechanism by which the XNFS server operations communicate with the mount server is not specified.

It should be noted that the file system objects must be local to the server system; XNFS does not support third party or proxy operations.

The ExpFileSysOp Operation

An XNFS server implementation will provide a mechanism by which a local file system object - a directory or file - is made available for mounting over the network by XNFS clients. The result of invoking this operation is the creation of an ExportedFileSystem object which is added to the set of exported file systems known to the mount server.

The ExpFileSysOp operation is invoked with a set of attributes which specify what is to be exported, which clients may mount the object, and how NFS accesses to the object are to be handled. These attributes are drawn from the attributes of the ExportedFileSystem object defined above; at a minimum, the PathName must be specified.

It is not permitted to export a file system object which is either a parent or a sub-directory of one which is currently exported and is within the same physical file system. This is because security considerations dictate that an XNFS server must disallow access to the parent directory of the exported file system object; if this constraint is violated, the server cannot enforce such a policy.

The ExpFileSysOp operation does not involve any direct protocol interaction with client systems.

The UnExpFileSysOp Operation

The UnExpFileSysOp operation may be used to make a previously exported file system object unavailable. The effect is to remove the specified ExportedFileSystem from the set of exported file systems known to the mount server and to destroy the object.

Only one attribute may be given.

The PathName attribute uniquely identifies the ExportedFileSystem object which is to be unexported.

If XNFS clients have previously mounted this file system, they may retain valid file handles for objects within the file system which is being unexported. The UnExpFileSysOp operation does not invalidate these file handles, which means that NFS operations to the file system may continue after the UnExpFileSysOp operation has been completed. An XNFS implementation may include a separate mechanism to forcibly invalidate existing file handles.

The execution of the UnExpFileSysOp operation does not involve any direct protocol interactions with XNFS client systems.

The ExpStdFileSysOp Operation

An XNFS server implementation may optionally provide a mechanism whereby a predefined sequence of ExpFileSysOp operations is executed. This sequence is performed by invoking the ExpStdFileSysOp operation, which will usually be a part of the system start-up sequence. To support this operation, the XNFS server will implement a StandardExports database. Each record in this database consists of a set of ExpFileSysOp attributes as described above. When the ExpStdFileSysOp operation is invoked, an ExpFileSysOp operation is performed for each record of the StandardExports database.

This specification does not describe the format of the StandardExports database, nor the mechanisms which may be used to manage it.

The UnExpStdFileSysOp Operation

The UnExpStdFileSysOp operation may be used to unexport every element of the StandardExports database. For each element of the database, it causes an UnExpFileSysOp operation to be invoked with the corresponding PathName attribute.

XNFS Client Operations

The five XNFS client administration operations are used to mount or unmount remote file system objects, or to determine what file systems are exported by a server. All except for ShowExpFileSysOp require appropriate privileges.

The ShowExpFileSysOp Operation

An XNFS client implementation will provide a mechanism by which the user may interrogate an XNFS server system to determine what file system objects are exported. The ShowExpFileSysOp operation is invoked with the following attribute:

For each ExportedFileSystem object exported by the XNFS server hostname, ShowExpFileSysOp will output the pathname together with a list of the hosts or groups listed in the Access attribute of the exported file system.

The ShowExpFileSysOp operation causes a MNTPROC_EXPORT RPC call to be performed to the mount server on the XNFS server system (see Name ). The mount server responds by sending a list of exported file system entries, which the ShowExpFileSysOp operation will render into a suitable form for output. This specification does not define this format.

The MntFileSysOp Operation

An XNFS client implementation will provide a mechanism by which a remote file system object - a directory or file exported by an XNFS server - is mounted. Mounting a remote file system consists of creating a MountedFileSystem object with the desired attributes, and associating it with a local file system object - the mountpoint - so that subsequent XSI references to the mountpoint will be interpreted as references to the remote file system object.

The attributes of the MntFileSysOp operation fall into two groups. The first consists of attributes for the MountedFileSystemObject as described above. The second is drawn from the following set of options which control the way in which the MntFileSysOp call is performed.

A fuller description of each attribute follows.

ReMount={True or False}

If True, the file system must already be mounted, otherwise an error results. If the Mode with which the file system was previously mounted is the same as that specified in this MntFileSysOp request, the operation has no effect. Otherwise the file system is unmounted and remounted.

MountRetryCount=nn, MountRetry={Background or Foreground}

If the first attempt to mount the file system fails due to a recoverable error (such as the server being temporarily inaccessible), and the MountRetryCount is non-zero, the request will be retried until it is successful or MountRetryCount attempts have been made. If MountRetry is specified as Background, a new process will be forked to perform the retries in the background, and the MntFileSysOp operation will terminate successfully.

The execution of the MntFileSysOp operation involves the acquisition of an NFS file handle for the exported file system object. This is realised by executing a MNTPROC_MNT RPC call to the mount server program on the XNFS server system, providing as an argument the pathname of the object (see Name ). The mount server interrogates the local XNFS server to retrieve a file handle for the object; if this is successful it examines the set of ExportedFileSystem objects established by ExpFileSysOp operations to find one which corresponds to that provided by the client. Having identified the exported file system, the mount server will verify access by the client based upon the attributes of the exported file system. If the mount is allowed, the file handle is returned to the XNFS client system. A MountedFileSystem object is created which includes the file handle and the attributes supplied in the MntFileSysOp invocation. The final procedure - binding the MountedFileSystem and file handle to the mountpoint on the client - is implementation-dependent, and is not specified by this standard.

The UnMntFileSysOp Operation

The UnMntFileSysOp operation will be used to unmount a previously mounted MountedFileSystem object. The file system may be identified by giving a (remote) PathName and Server, or by specifying the (local) MountPoint. Upon completion of the UnMntFileSysOp operation, the previous contents of the mountpoint will once more be accessible.

An implementation is not required to support both mechanisms to specify the file system to be unmounted.

A fuller description of each attribute follows.

PathName=pathname

This attribute identifies the remote file system object to be unmounted.

Server=hostname

This attribute identifies the XNFS server system from which the object was mounted.

MountPoint=pathname

This attribute identifies the local file system object on which the XNFS object was mounted.

If the mounted file system is in use, the UnMntFileSysOp operation will fail with an appropriate error indication. The definition of "in use" is implementation-dependent.

The execution of the UnMntFileSysOp operation causes a MNTPROC_UMNT RPC to be made to the mount server process on the XNFS server system with the pathname as an argument (see Name ).

The MntStdFileSysOp Operation

An XNFS client implementation may provide a mechanism by which a predefined sequence of MntFileSysOp operations is executed. This sequence is performed by invoking the MntStdFileSysOp operation, which will usually be a part of the system start-up sequence. To realise this mechanism, a StandardMounts database will exist. Each record in this database consists of a set of MntFileSysOp attributes as described above. When the MntStdFileSysOp operation is invoked, a MntFileSysOp operation is performed for each record of the StandardMounts database.

This specification does not describe the format of the StandardMounts database, nor the mechanisms which may be used to manage it.

The UnMntAllFileSys Operation

An XNFS client implementation may include an UnMntAllFileSys operation which may be used to unmount some or all mounted file systems.

A fuller description of each attribute follows.

Server=hostname

If this attribute is given, all file systems mounted from the given XNFS server are unmounted. If it is not, all NFS file systems which are mounted by the client are unmounted.

For each MountedFileSystem object which is to be unmounted, an UnMntFileSysOp operation is invoked with the corresponding PathName and Server attributes.

File and Directory Operations

Unlike the administrative part of the model, file and directory access is precisely specified. The client system must implement a mechanism whereby every active file or directory object is marked as local or remote. For each active remote object the file handle and MountedFileSystem must be recorded. Whenever a process executing on the client invokes an XSI function which refers to a remote file or directory, the XNFS client implementation must interpret this request in terms of NFS remote procedure calls. Open Systems Transmission Analysis indicates, but does not completely specify, how this may be achieved. XDR Protocol Specification , Remote Procedure Calls: Protocol Specification , RPC Interface to UDP Transport Services and XNFS: Protocol Specification, Version 2 define how NFS requests are constructed and transmitted to the server. The XNFS server implementation is responsible for performing UID mapping according to the values of the AnonMapping and Root attributes of the ExportedFileSystem, interpreting the resulting request in terms of local file system operations and transmitting the response to the client. Semantic Difference Summary for File Access , Open-System Interface Semantics over XNFS and Open System Utilities Semantics over XNFS indicate, but do not fully specify, the deviations from standard XSI semantics which may occur.

File locking operations are discussed separately in File Locking over XNFS , Network Lock Manager Protocol and Network Status Monitor Protocol .

Operation in an International Environment

XNFS can operate in a situation where more than one natural language and cultural environment is in use. There may be different environments on client and server and there may be different environments used within the client or the server.

The internationalisation facilities that are available and the considerations that apply are discussed in the X/Open Internationalisation Guide. When the client is implemented in accordance with its provisions, internationalisation facilities are available, transparently, on the resulting distributed file system.

Two particular considerations are discussed below.

Internationalized XNFS Operations

It is desirable that the XNFS client and server administrative operations should be internationalized. This means that each user can invoke these operations via a user interface that recognizes the character set, collating sequence, date format and other conventions of their cultural environment and that accepts commands and displays text expressed in their natural language. It is recommended that implementations include internationalized administrative operations implemented in accordance with the recommendations of the X/Open Internationalisation Guide.

Remote File Systems Created in Different Locales

It is possible to access a file system that has been created on the server in a locale that is not in use, or even not available, on the client. This may give rise to unpredictable results. For example, filenames created using character sets that are not supported on the client may be displayed incorrectly. This problem can arise within a single system on which several locales are available, but is more likely to occur when XNFS is used to provide transparent file access across several different systems, and users should beware.