rfc1813.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

Network Working Group                                       B. Callaghan
Request for Comments: 1813                                  B. Pawlowski
Category: Informational                                      P. Staubach
                                                  Sun Microsystems, Inc.
                                                               June 1995


                  NFS Version 3 Protocol Specification

Status of this Memo

   This memo provides information for the Internet community.
   This memo does not specify an Internet standard of any kind.
   Distribution of this memo is unlimited.

IESG Note

   Internet Engineering Steering Group comment: please note that
   the IETF is not involved in creating or maintaining this
   specification.  This is the significance of the specification
   not being on the standards track.

Abstract

   This paper describes the NFS version 3 protocol.  This paper is
   provided so that people can write compatible implementations.

Table of Contents

   1.    Introduction . . . . . . . . . . . . . . . . . . . . . . .   3
   1.1     Scope of the NFS version 3 protocol  . . . . . . . . . .   4
   1.2     Useful terms . . . . . . . . . . . . . . . . . . . . . .   5
   1.3     Remote Procedure Call  . . . . . . . . . . . . . . . . .   5
   1.4     External Data Representation . . . . . . . . . . . . . .   5
   1.5     Authentication and Permission Checking . . . . . . . . .   7
   1.6     Philosophy . . . . . . . . . . . . . . . . . . . . . . .   8
   1.7     Changes from the NFS version 2 protocol  . . . . . . . .  11
   2.    RPC Information  . . . . . . . . . . . . . . . . . . . . .  14
   2.1     Authentication . . . . . . . . . . . . . . . . . . . . .  14
   2.2     Constants  . . . . . . . . . . . . . . . . . . . . . . .  14
   2.3     Transport address  . . . . . . . . . . . . . . . . . . .  14
   2.4     Sizes  . . . . . . . . . . . . . . . . . . . . . . . . .  14
   2.5     Basic Data Types . . . . . . . . . . . . . . . . . . . .  15
   2.6     Defined Error Numbers  . . . . . . . . . . . . . . . . .  17
   3.    Server Procedures  . . . . . . . . . . . . . . . . . . . .  27
   3.1     General comments on attributes . . . . . . . . . . . . .  29
   3.2     General comments on filenames  . . . . . . . . . . . . .  30
   3.3.0   NULL: Do nothing . . . . . . . . . . . . . . . . . . . .  31



Callaghan, el al             Informational                      [Page 1]

RFC 1813                 NFS Version 3 Protocol                June 1995


   3.3.1   GETATTR: Get file attributes . . . . . . . . . . . . . .  32
   3.3.2   SETATTR: Set file attributes . . . . . . . . . . . . . .  33
   3.3.3   LOOKUP: Lookup filename  . . . . . . . . . . . . . . . .  37
   3.3.4   ACCESS: Check access permission  . . . . . . . . . . . .  40
   3.3.5   READLINK: Read from symbolic link  . . . . . . . . . . .  44
   3.3.6   READ: Read from file . . . . . . . . . . . . . . . . . .  46
   3.3.7   WRITE: Write to file . . . . . . . . . . . . . . . . . .  49
   3.3.8   CREATE: Create a file  . . . . . . . . . . . . . . . . .  54
   3.3.9   MKDIR: Create a directory  . . . . . . . . . . . . . . .  58
   3.3.10  SYMLINK: Create a symbolic link  . . . . . . . . . . . .  61
   3.3.11  MKNOD: Create a special device . . . . . . . . . . . . .  63
   3.3.12  REMOVE: Remove a file  . . . . . . . . . . . . . . . . .  67
   3.3.13  RMDIR: Remove a directory  . . . . . . . . . . . . . . .  69
   3.3.14  RENAME: Rename a file or directory . . . . . . . . . . .  71
   3.3.15  LINK: Create link to an object . . . . . . . . . . . . .  74
   3.3.16  READDIR: Read From directory . . . . . . . . . . . . . .  76
   3.3.17  READDIRPLUS: Extended read from directory  . . . . . . .  80
   3.3.18  FSSTAT: Get dynamic file system information  . . . . . .  84
   3.3.19  FSINFO: Get static file system information . . . . . . .  86
   3.3.20  PATHCONF: Retrieve POSIX information . . . . . . . . . .  90
   3.3.21  COMMIT: Commit cached data on a server to stable storage  92
   4.    Implementation issues  . . . . . . . . . . . . . . . . . .  96
   4.1     Multiple version support . . . . . . . . . . . . . . . .  96
   4.2     Server/client relationship . . . . . . . . . . . . . . .  96
   4.3     Path name interpretation . . . . . . . . . . . . . . . .  97
   4.4     Permission issues  . . . . . . . . . . . . . . . . . . .  98
   4.5     Duplicate request cache  . . . . . . . . . . . . . . . .  99
   4.6     File name component handling . . . . . . . . . . . . . . 101
   4.7     Synchronous modifying operations . . . . . . . . . . . . 101
   4.8     Stable storage . . . . . . . . . . . . . . . . . . . . . 101
   4.9     Lookups and name resolution  . . . . . . . . . . . . . . 102
   4.10    Adaptive retransmission  . . . . . . . . . . . . . . . . 102
   4.11    Caching policies . . . . . . . . . . . . . . . . . . . . 102
   4.12    Stable versus unstable writes. . . . . . . . . . . . . . 103
   4.13    32 bit clients/servers and 64 bit clients/servers. . . . 104
   5.    Appendix I: Mount protocol . . . . . . . . . . . . . . . . 106
   5.1     RPC Information  . . . . . . . . . . . . . . . . . . . . 106
   5.1.1     Authentication . . . . . . . . . . . . . . . . . . . . 106
   5.1.2     Constants  . . . . . . . . . . . . . . . . . . . . . . 106
   5.1.3     Transport address  . . . . . . . . . . . . . . . . . . 106
   5.1.4     Sizes  . . . . . . . . . . . . . . . . . . . . . . . . 106
   5.1.5     Basic Data Types . . . . . . . . . . . . . . . . . . . 106
   5.2     Server Procedures  . . . . . . . . . . . . . . . . . . . 107
   5.2.0     NULL: Do nothing . . . . . . . . . . . . . . . . . . . 108
   5.2.1     MNT: Add mount entry . . . . . . . . . . . . . . . . . 109
   5.2.2     DUMP: Return mount entries . . . . . . . . . . . . . . 110
   5.2.3     UMNT: Remove mount entry . . . . . . . . . . . . . . . 111
   5.2.4     UMNTALL: Remove all mount entries  . . . . . . . . . . 112



Callaghan, el al             Informational                      [Page 2]

RFC 1813                 NFS Version 3 Protocol                June 1995


   5.2.5     EXPORT: Return export list . . . . . . . . . . . . . . 113
   6.    Appendix II: Lock manager protocol . . . . . . . . . . . . 114
   6.1     RPC Information  . . . . . . . . . . . . . . . . . . . . 114
   6.1.1     Authentication . . . . . . . . . . . . . . . . . . . . 114
   6.1.2     Constants  . . . . . . . . . . . . . . . . . . . . . . 114
   6.1.3     Transport Address  . . . . . . . . . . . . . . . . . . 115
   6.1.4     Basic Data Types . . . . . . . . . . . . . . . . . . . 115
   6.2     NLM Procedures . . . . . . . . . . . . . . . . . . . . . 118
   6.2.0     NULL: Do nothing . . . . . . . . . . . . . . . . . . . 120
   6.3     Implementation issues  . . . . . . . . . . . . . . . . . 120
   6.3.1     64-bit offsets and lengths . . . . . . . . . . . . . . 120
   6.3.2     File handles . . . . . . . . . . . . . . . . . . . . . 120
   7.    Appendix III: Bibliography . . . . . . . . . . . . . . . . 122
   8.    Security Considerations  . . . . . . . . . . . . . . . . . 125
   9.    Acknowledgements . . . . . . . . . . . . . . . . . . . . . 125
   10.   Authors' Addresses . . . . . . . . . . . . . . . . . . . . 126

1. Introduction

   Sun's NFS protocol provides transparent remote access to shared
   file systems across 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 of the NFS
   version 2 protocol exist for a variety of machines, from personal
   computers to supercomputers. The initial version of the NFS
   protocol is specified in the Network File System Protocol
   Specification [RFC1094]. A description of the initial
   implementation can be found in [Sandberg].

   The supporting MOUNT protocol performs the operating
   system-specific functions that allow clients to attach remote
   directory trees to a point within the local file system. The
   mount process also allows the server to grant remote access
   privileges to a restricted set of clients via export control.

   The Lock Manager provides support for file locking when used in
   the NFS environment. The Network Lock Manager (NLM) protocol
   isolates the inherently stateful aspects of file locking into a
   separate protocol.

   A complete description of the above protocols and their
   implementation is to be found in [X/OpenNFS].

   The purpose of this document is to:





Callaghan, el al             Informational                      [Page 3]

RFC 1813                 NFS Version 3 Protocol                June 1995


        o Specify the NFS version 3 protocol.

        o Describe semantics of the protocol through annotation
          and description of intended implementation.

        o Specify the MOUNT version 3 protocol.

        o Briefly describe the changes between the NLM version 3
          protocol and the NLM version 4 protocol.

   The normative text is the description of the RPC procedures and
   arguments and results, which defines the over-the-wire protocol,
   and the semantics of those procedures. The material describing
   implementation practice aids the understanding of the protocol
   specification and describes some possible implementation issues
   and solutions. It is not possible to describe all implementations
   and the UNIX operating system implementation of the NFS version 3
   protocol is most often used to provide examples. Given that, the
   implementation discussion does not bear the authority of the
   description of the over-the-wire protocol itself.

1.1 Scope of the NFS version 3 protocol

   This revision of the NFS protocol addresses new requirements.
   The need to support larger files and file systems has prompted
   extensions to allow 64 bit file sizes and offsets. The revision
   enhances security by adding support for an access check to be
   done on the server. Performance modifications are of three
   types:

   1. The number of over-the-wire packets for a given
      set of file operations is reduced by returning file
      attributes on every operation, thus decreasing the number
      of calls to get modified attributes.

   2. The write throughput bottleneck caused by the synchronous
      definition of write in the NFS version 2 protocol has been
      addressed by adding support so that the NFS server can do
      unsafe writes. Unsafe writes are writes which have not
      been committed to stable storage before the operation
      returns.  This specification defines a method for
      committing these unsafe writes to stable storage in a
      reliable way.

   3. Limitations on transfer sizes have been relaxed.

   The ability to support multiple versions of a protocol in RPC
   will allow implementors of the NFS version 3 protocol to define



Callaghan, el al             Informational                      [Page 4]

RFC 1813                 NFS Version 3 Protocol                June 1995


   clients and servers that provide backwards compatibility with
   the existing installed base of NFS version 2 protocol
   implementations.

   The extensions described here represent an evolution of the
   existing NFS protocol and most of the design features of the
   NFS protocol described in [Sandberg] persist. See Changes
   from the NFS version 2 protocol on page 11 for a more
   detailed summary of the changes introduced by this revision.

1.2 Useful terms

   In this specification, a "server" is a machine that provides
   resources to the network; a "client" is a machine that accesses
   resources over the network; a "user" is a person logged in on a
   client; an "application" is a program that executes on a client.

1.3 Remote Procedure Call

   The Sun Remote Procedure Call specification provides a
   procedure-oriented interface to remote services. Each server
   supplies a program, which is a set of procedures. The NFS
   service is one such program. The combination of host address,
   program number, version number, and procedure number specify one
   remote service procedure.  Servers can support multiple versions
   of a program by using different protocol version numbers.

   The NFS protocol was designed to not require any specific level
   of reliability from its lower levels so it could potentially be
   used on many underlying transport protocols. The NFS service is
   based on RPC which provides the abstraction above lower level
   network and transport protocols.

   The rest of this document assumes the NFS environment is
   implemented on top of Sun RPC, which is specified in [RFC1057].
   A complete discussion is found in [Corbin].

1.4 External Data Representation

   The eXternal Data Representation (XDR) specification provides a
   standard way of representing a set of data types on a network.
   This solves the problem of different byte orders, structure
   alignment, and data type representation on different,
   communicating machines.

   In this document, the RPC Data Description Language is used to
   specify the XDR format parameters and results to each of the RPC
   service procedures that an NFS server provides. The RPC Data



Callaghan, el al             Informational                      [Page 5]

RFC 1813                 NFS Version 3 Protocol                June 1995


   Description Language is similar to declarations in the C
   programming language. A few new constructs have been added.
   The notation:

      string  name[SIZE];
      string  data<DSIZE>;

   defines name, which is a fixed size block of SIZE bytes, and
   data, which is a variable sized block of up to DSIZE bytes. This
   notation indicates fixed-length arrays and arrays with a
   variable number of elements up to a fixed maximum. A
   variable-length definition with no size specified means there is
   no maximum size for the field.

   The discriminated union definition:

      union example switch (enum status) {
           case OK:
              struct {
                 filename      file1;
                 filename      file2;
                 integer       count;
              }
           case ERROR:
              struct {
                 errstat       error;
                 integer       errno;
              }
           default:
              void;
      }

   defines a structure where the first thing over the network is an
   enumeration type called status. If the value of status is OK,
   the next thing on the network will be the structure containing
   file1, file2, and count. Else, if the value of status is ERROR,
   the next thing on the network will be a structure containing
   error and errno.  If the value of status is neither OK nor
   ERROR, then there is no more data in the structure.

   The XDR type, hyper, is an 8 byte (64 bit) quantity. It is used
   in the same way as the integer type. For example:

      hyper          foo;
      unsigned hyper bar;

   foo is an 8 byte signed value, while bar is an 8 byte unsigned
   value.