doc: Add RFC documents

1 files changed, 899 insertions, 0 deletions

diff --git a/doc/rfc/rfc2054.txt b/doc/rfc/rfc2054.txt
new file mode 100644
index 0000000..71ebca5
--- /dev/null
+++ b/doc/rfc/rfc2054.txt
@@ -0,0 +1,899 @@
+
+
+
+
+
+
+Network Working Group                                       B. Callaghan
+Request for Comments: 2054                        Sun Microsystems, Inc.
+Category: Informational                                     October 1996
+
+
+                      WebNFS Client 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.
+
+Abstract
+
+   This document describes a lightweight binding mechanism that allows
+   NFS clients to obtain service from WebNFS-enabled servers with a
+   minimum of protocol overhead.  In removing this overhead, WebNFS
+   clients see benefits in faster response to requests, easy transit of
+   packet filter firewalls and TCP-based proxies, and better server
+   scalability.
+
+Table of Contents
+
+   1.    Introduction . . . . . . . . . . . . . . . . . . . . . . . 2
+   2.    TCP vs UDP . . . . . . . . . . . . . . . . . . . . . . . . 2
+   3.    Well-known Port  . . . . . . . . . . . . . . . . . . . . . 2
+   4.    NFS Version 3  . . . . . . . . . . . . . . . . . . . . . . 3
+   4.1     Transfer Size  . . . . . . . . . . . . . . . . . . . . . 3
+   4.2     Fast Writes  . . . . . . . . . . . . . . . . . . . . . . 4
+   4.3     READDIRPLUS  . . . . . . . . . . . . . . . . . . . . . . 4
+   5.    Public Filehandle  . . . . . . . . . . . . . . . . . . . . 5
+   5.1     NFS Version 2 Public Filehandle  . . . . . . . . . . . . 5
+   5.2     NFS Version 3 Public Filehandle  . . . . . . . . . . . . 5
+   6.    Multi-component Lookup . . . . . . . . . . . . . . . . . . 6
+   6.1     Canonical Path vs. Native Path . . . . . . . . . . . . . 6
+   6.2     Symbolic Links . . . . . . . . . . . . . . . . . . . . . 7
+   6.2.1     Absolute Link  . . . . . . . . . . . . . . . . . . . . 8
+   6.2.2     Relative Link  . . . . . . . . . . . . . . . . . . . . 8
+   6.3     Filesystem Spanning Pathnames  . . . . . . . . . . . . . 9
+   7.    Contacting the Server  . . . . . . . . . . . . . . . . . . 9
+   8.    Mount Protocol . . . . . . . . . . . . . . . . . . . . . . 11
+   9.    Exploiting Concurrency . . . . . . . . . . . . . . . . . . 12
+   9.1     Read-ahead . . . . . . . . . . . . . . . . . . . . . . . 12
+   9.2     Concurrent File Download . . . . . . . . . . . . . . . . 13
+   10.   Timeout and Retransmission . . . . . . . . . . . . . . . . 13
+   11.   Bibliography . . . . . . . . . . . . . . . . . . . . . . . 15
+   12.   Security Considerations  . . . . . . . . . . . . . . . . . 16
+
+
+
+Callaghan                    Informational                      [Page 1]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   13.   Acknowledgements . . . . . . . . . . . . . . . . . . . . . 16
+   14.   Author's Address . . . . . . . . . . . . . . . . . . . . . 16
+
+1. Introduction
+
+   The NFS protocol provides access to shared filesystems across
+   networks.  It is designed to be machine, operating system, network
+   architecture, and transport protocol independent.  The protocol
+   currently exists in two versions: version 2 [RFC1094] and version 3
+   [RFC1813], both built on Sun RPC [RFC1831] at its associated eXternal
+   Data Representation (XDR) [RFC1832] and Binding Protocol [RFC1833].
+
+   WebNFS provides additional semantics that can be applied to NFS
+   version 2 and 3 to eliminate the overhead of PORTMAP and MOUNT
+   protocols, make the protocol easier to use where firewall transit is
+   required, and reduce the number of LOOKUP requests required to
+   identify a particular file on the server. WebNFS server requirements
+   are described in RFC 2055.
+
+2. TCP vs UDP
+
+   The NFS protocol is most well known for its use of UDP which performs
+   acceptably on local area networks.  However, on wide area networks
+   with error prone, high-latency connections and bandwidth contention,
+   TCP is well respected for its congestion control and superior error
+   handling.  A growing number of NFS implementations now support the
+   NFS protocol over TCP connections.
+
+   Use of NFS version 3 is particularly well matched to the use of TCP
+   as a transport protocol.  Version 3 removes the arbitrary 8k transfer
+   size limit of version 2, allowing the READ or WRITE of very large
+   streams of data over a TCP connection.  Note that NFS version 2 is
+   also supported on TCP connections, though the benefits of TCP data
+   streaming will not be as great.
+
+   A WebNFS client must first attempt to connect to its server with a
+   TCP connection.  If the server refuses the connection, the client
+   should attempt to use UDP.
+
+3. Well-known Port
+
+   While Internet protocols are generally identified by registered port
+   number assignments, RPC based protocols register a 32 bit program
+   number and a dynamically assigned port with the portmap service which
+   is registered on the well-known port 111.  Since the NFS protocol is
+   RPC-based, NFS servers register their port assignment with the
+   portmap service.
+
+
+
+
+Callaghan                    Informational                      [Page 2]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   NFS servers are constrained by a requirement to re-register at the
+   same port after a server crash and recovery so that clients can
+   recover simply by retransmitting an RPC request until a response is
+   received.  This is simpler than the alternative of having the client
+   repeatedly check with the portmap service for a new port assignment.
+   NFS servers typically achieve this port invariance by registering a
+   constant port assignment, 2049, for both UDP and TCP.
+
+   To avoid the overhead of contacting the server's portmap service, and
+   to facilitate transit through packet filtering firewalls, WebNFS
+   clients optimistically assume that WebNFS servers register on port
+   2049.  Most NFS servers use this port assignment already, so this
+   client optimism is well justified. Refer to section 8 for further
+   details on port binding.
+
+4. NFS Version 3
+
+   NFS version 3 corrects deficiencies in version 2 of the protocol as
+   well as providing a number of features suitable to WebNFS clients
+   accessing servers over high-latency, low-bandwidth connections.
+
+4.1 Transfer Size
+
+   NFS version 2 limited the amount of data in a single request or reply
+   to 8 kilobytes.  This limit was based on what was then considered a
+   reasonable upper bound on the amount of data that could be
+   transmitted in a UDP datagram across an Ethernet.  The 8k transfer
+   size limitation affects READ, WRITE, and READDIR requests. When using
+   version 2, a WebNFS client must not transmit any request that exceeds
+   the 8k transfer size.  Additionally, the client must be able to
+   adjust its requests to suit servers that limit transfer sizes to
+   values smaller than 8k.
+
+   NFS version 3 removes the 8k limit, allowing the client and server to
+   negotiate whatever limit they choose.  Larger transfer sizes are
+   preferred since they require fewer READ or WRITE requests to transfer
+   a given amount of data and utilize a TCP stream more efficiently.
+
+   While the client can use the FSINFO procedure to request the server's
+   maximum and preferred transfer sizes, in the interests of keeping the
+   number of NFS requests to a minimum, WebNFS clients should
+   optimistically choose a transfer size and make corrections if
+   necessary based on the server's response.
+
+   For instance, given that the file attributes returned with the
+   filehandle from a LOOKUP request indicate that the file has a size of
+   50k, the client might transmit a READ request for 50k.  If the server
+   returns only 32k, then the client can assume that the server's
+
+
+
+Callaghan                    Informational                      [Page 3]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   maximum transfer size is 32k and issue another read request for the
+   remaining data.  The server will indicate positively when the end of
+   file is reached.
+
+   A similar strategy can be used when writing to a file on the server,
+   though the client should be more conservative in choosing write
+   request sizes so as to avoid transmitting large amounts of data that
+   the server cannot handle.
+
+4.2 Fast Writes
+
+   NFS version 2 requires the server to write client data to stable
+   storage before responding to the client.  This avoids the possibility
+   of the the server crashing and losing the client's data after a
+   positive response.  While this requirement protects the client from
+   data loss, it requires that the server direct client write requests
+   directly to the disk, or to buffer client data in expensive non-
+   volatile memory (NVRAM).  Either way, the effect is poor write
+   performance, either through inefficient synchronous writes to the
+   disk or through the limited buffering available in NVRAM.
+
+   NFS version 3 provides clients with the option of having the server
+   buffer a series of WRITE requests in unstable storage.  A subsequent
+   COMMIT request from the client will have the server flush the data to
+   stable storage and have the client verify that the server lost none
+   of the data.  Since fast writes benefit both the client and the
+   server, WebNFS clients should use WRITE/COMMIT when writing to the
+   server.
+
+4.3 READDIRPLUS
+
+   The NFS version 2 READDIR procedure is also supported in version 3.
+   READDIR returns the names of the entries in a directory along with
+   their fileids.  Browser programs that display directory contents as a
+   list will usually display more than just the filename; a different
+   icon may be displayed if the entry is a directory or a file.
+   Similarly, the browser may display the file size, and date of last
+   modification.
+
+   Since this additional information is not returned by READDIR, version
+   2 clients must issue a series of LOOKUP requests, one per directory
+   member, to retrieve the attribute data.  Clearly this is an expensive
+   operation where the directory is large (perhaps several hundred
+   entries) and the network latency is high.
+
+   The version 3 READDIRPLUS request allows the client to retrieve not
+   only the names of the directory entries, but also their file
+   attributes and filehandles in a single call.  WebNFS clients that
+
+
+
+Callaghan                    Informational                      [Page 4]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   require attribute information for directory entries should use
+   READDIRPLUS in preference to READDIR.
+
+5. Public Filehandle
+
+   NFS filehandles are normally created by the server and used to
+   identify uniquely a particular file or directory on the server.  The
+   client does not normally create filehandles or have any knowledge of
+   the contents of a filehandle.
+
+   The public filehandle is an an exception.  It is an NFS filehandle
+   with a reserved value and special semantics that allow an initial
+   filehandle to be obtained.  A WebNFS client can use the public
+   filehandle as an initial filehandle rather than using the MOUNT
+   protocol.  Since NFS version 2 and version 3 have different
+   filehandle formats, the public filehandle is defined differently for
+   each.
+
+   The public filehandle is a zero filehandle.  For NFS version 2 this
+   is a filehandle with 32 zero octets.  A version 3 public filehandle
+   has zero length.
+
+5.1 NFS Version 2 Public Filehandle
+
+   A version 2 filehandle is defined in RFC 1094 as an opaque value
+   occupying 32 octets.  A version 2 public filehandle has a zero in
+   each octet, i.e. all zeros.
+
+    1                                                             32
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+   |0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|0|
+   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+5.2 NFS Version 3 Public Filehandle
+
+   A version 3 filehandle is defined in RFC 1813 as a variable length
+   opaque value occupying up to 64 octets.  The length of the filehandle
+   is indicated by an integer value contained in a 4 octet value which
+   describes the number of valid octets that follow. A version 3 public
+   filehandle has a length of zero.
+
+   +-+-+-+-+
+   |   0   |
+   +-+-+-+-+
+
+
+
+
+
+
+
+Callaghan                    Informational                      [Page 5]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+6. Multi-component Lookup
+
+   Normally the NFS LOOKUP request (version 2 or 3) takes a directory
+   filehandle along with the name of a directory member, and returns the
+   filehandle of the directory member.  If a client needs to evaluate a
+   pathname that contains a sequence of components, then beginning with
+   the directory filehandle of the first component it must issue a
+   series of LOOKUP requests one component at a time.  For instance,
+   evaluation of the Unix path  "a/b/c" will generate separate LOOKUP
+   requests for each component of the pathname "a", "b", and "c".
+
+   A LOOKUP request that uses the public filehandle can provide a
+   pathname containing multiple components.  The server is expected to
+   evaluate the entire pathname and return a filehandle for the final
+   component. Both canonical (slash-separated) and server native
+   pathnames are supported.
+
+   For example, rather than evaluate the path "a/b/c" as:
+
+        LOOKUP  FH=0x0  "a"  --->
+                             <---  FH=0x1
+        LOOKUP  FH=0x1  "b"  --->
+                             <---  FH=0x2
+        LOOKUP  FH=0x2  "c"  --->
+                             <---  FH=0x3
+
+   Relative to the public filehandle these three LOOKUP requests can be
+   replaced by a single multi-component lookup:
+
+        LOOKUP  FH=0x0  "a/b/c"  --->
+                                 <---  FH=0x3
+
+   Multi-component lookup is supported only for LOOKUP requests relative
+   to the public filehandle.
+
+6.1 Canonical Path vs. Native Path
+
+   If the pathname in a multi-component LOOKUP request begins with an
+   ASCII character, then it must be a canonical path.  A canonical path
+   is a hierarchically-related, slash-separated sequence of components,
+   <directory>/<directory>/.../<name>.  Occurrences of the "/" character
+   within a component must be escaped using the escape code %2f.  Non-
+   ascii characters within components must also be escaped using the "%"
+   character to introduce a two digit hexadecimal code. Occurrences of
+   the "%" character that do not introduce an encoded character must
+   themselves be encoded with %25.
+
+
+
+
+
+Callaghan                    Informational                      [Page 6]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   If the first character of the path is a slash, then the canonical
+   path will be evaluated relative to the server's root directory.  If
+   the first character is not a slash, then the path will be evaluated
+   relative to the directory with which the public filehandle is
+   associated.
+
+   Not all WebNFS servers can support arbitrary use of absolute paths.
+   Clearly, the server cannot return a filehandle if the path identifies
+   a file or directory that is not exported by the server.  In addition,
+   some servers will not return a filehandle if the path names a file or
+   directory in an exported filesystem different from the one that is
+   associated with the public filehandle.
+
+   If the first character of the path is 0x80 (non-ascii) then the
+   following character is the first in a native path.  A native path
+   conforms to the normal pathname syntax of the server. For example:
+
+        Lookup for Canonical Path:
+
+                LOOKUP FH=0x0 "/a/b/c"
+
+        Lookup for Native Path:
+
+                LOOKUP FH=0x0  0x80 "a:b:c"
+
+6.2 Symbolic Links
+
+   On Unix servers, components within a pathname may be symbolic links.
+   The server will evaluate these symbolic links as a part of the normal
+   pathname evaluation process.  If the final component is a symbolic
+   link, the server will return its filehandle, rather than evaluate it.
+
+   If the attributes returned with a filehandle indicate that it refers
+   to a symbolic link, then it is the client's responsibility to deal
+   with the link by fetching the contents of the link using the READLINK
+   procedure. What follows is determined by the contents of the link.
+
+   Evaluation of symbolic links by the client is defined only if the
+   symbolic link is retrieved via the multi-component lookup of a
+   canonical path.
+
+
+
+
+
+
+
+
+
+
+
+Callaghan                    Informational                      [Page 7]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+6.2.1 Absolute Link
+
+   If the first character of the link text is a slash "/", then the
+   following path can be assumed to be absolute.  The entire path must
+   be evaluated by the server relative to the public filehandle:
+
+        LOOKUP  FH=0x0  "a/b"  --->
+                               <---  FH=0x1 (symbolic link)
+        READLINK FH=0x1        --->
+                               <---  "/x/y"
+        LOOKUP  FH=0x0  "/x/y"
+                               <---  FH=0x2
+
+   So in this case the client just passes the link text back to the
+   server for evaluation.
+
+6.2.2 Relative Link
+
+   If the first character of the link text is not a slash, then the
+   following path can be assumed to be relative to the location of the
+   symbolic link.  To evaluate this correctly, the client must
+   substitute the link text in place of the final pathname component
+   that named the link and issue a another LOOKUP relative to the public
+   filehandle.
+
+        LOOKUP  FH=0x0  "a/b"  --->
+                               <---  FH=0x1 (symbolic link)
+        READLINK FH=0x1        --->
+                               <---  "x/y"
+        LOOKUP  FH=0x0  "a/x/y"
+                               <---  FH=0x2
+
+   By substituting the link text in the link path and having the server
+   evaluate the new path, the server effectively gets to evaluate the
+   link relative to the link's location.
+
+   The client may also "clean up" the resulting pathname by removing
+   redundant components as described in Section 4. of RFC 1808.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Callaghan                    Informational                      [Page 8]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+6.3 Filesystem Spanning Pathnames
+
+   NFS LOOKUP requests normally do not cross from one filesystem to
+   another on the server.  For instance if the server has the following
+   export and mounts:
+
+      /export           (exported)
+
+      /export/bigdata   (mountpoint)
+
+   then an NFS LOOKUP for "bigdata" using the filehandle for "/export"
+   will return a "no file" error because the LOOKUP request did not
+   cross the mountpoint on the server.  There is a practical reason for
+   this limitation: if the server permitted the mountpoint crossing to
+   occur, then a Unix client might receive ambiguous fileid information
+   inconsistent with it's view of a single remote mount for "/export".
+   It is expected that the client resolve this by mirroring the
+   additional server mount, e.g.
+
+      Client                           Server
+
+      /mnt         <--- mounted on --- /export
+
+      /mnt/bigdata <--- mounted on --- /export/bigdata
+
+   However, this semantic changes if the client issues the filesystem
+   spanning LOOKUP relative to the public filehandle. If the following
+   filesystems are exported:
+
+      /export           (exported public)
+
+      /export/bigdata   (exported mountpoint)
+
+   then an NFS LOOKUP for "bigdata" relative to the public filehandle
+   will cross the mountpoint - just as if the client had issued a MOUNT
+   request - but only if the new filesystem is exported, and only if the
+   server supports Export Spanning Pathnames described in Section 6.3 of
+   RFC 2055 [RFC2055].
+
+7. Contacting the Server
+
+   WebNFS clients should be optimistic in assuming that the server
+   supports WebNFS, but should be capable of fallback to conventional
+   methods for server access if the server does not support WebNFS.
+
+
+
+
+
+
+
+Callaghan                    Informational                      [Page 9]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   The client should start with the assumption that the server supports:
+
+     - NFS version 3.
+
+     - NFS TCP connections.
+
+     - Public Filehandles.
+
+   If these assumptions are not met, the client should fall back
+   gracefully with a minimum number of messages. The following steps are
+   recommended:
+
+   1. Attempt to create a TCP connection to the server's
+      port 2049.
+
+      If the connection fails then assume that a request
+      sent over UDP will work.  Use UDP port 2049.
+
+      Do not use the PORTMAP protocol to determine the
+      server's port unless the server does not respond to
+      port 2049 for both TCP and UDP.
+
+   2. Assume WebNFS and V3 are supported.
+      Send an NFS version 3 LOOKUP with the public filehandle
+      for the requested pathname.
+
+      If the server returns an RPC PROG_MISMATCH error then
+      assume that NFS version 3 is not supported.  Retry
+      the LOOKUP with an NFS version 2 public filehandle.
+
+      Note: The first call may not necessarily be a LOOKUP
+      if the operation is directed at the public filehandle
+      itself, e.g. a READDIR or READDIRPLUS of the directory
+      that is associated with the public filehandle.
+
+      If the server returns an NFS3ERR_STALE, NFS3ERR_INVAL, or
+      NFS3ERR_BADHANDLE error, then assume that the server does
+      not support WebNFS since it does not recognize the public
+      filehandle. The client must use the server's portmap
+      service to locate and use the MOUNT protocol to obtain an
+      initial filehandle for the requested path.
+
+   WebNFS clients can benefit by caching information about the server:
+   whether the server supports TCP connections (if TCP is supported then
+   the client should cache the TCP connection as well), which protocol
+   the server supports and whether the server supports public
+   filehandles.  If the server does not support public filehandles, the
+   client may choose to cache the port assignment of the MOUNT service
+
+
+
+Callaghan                    Informational                     [Page 10]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   as well as previously used pathnames and their filehandles.
+
+8. Mount Protocol
+
+   If the server returns an error to the client that indicates no
+   support for public filehandles, the client must use the MOUNT
+   protocol to convert the given pathname to a filehandle.  Version 1 of
+   the MOUNT protocol is described in Appendix A of RFC 1094 and version
+   3 in Appendix I of RFC 1813. Version 2 of the MOUNT protocol is
+   identical to version 1 except for the addition of a procedure
+   MOUNTPROC_PATHCONF which returns POSIX pathconf information from the
+   server.
+
+   At this point the client must already have some indication as to
+   which version of the NFS protocol is supported on the server.  Since
+   the filehandle format differs between NFS versions 2 and 3, the
+   client must select the appropriate version of the MOUNT protocol.
+   MOUNT versions 1 and 2 return only NFS version 2 filehandles, whereas
+   MOUNT version 3 returns NFS version 3 filehandles.
+
+   Unlike the NFS service, the MOUNT service is not registered on a
+   well-known port.  The client must use the PORTMAP service to locate
+   the server's MOUNT port before it can transmit a MOUNTPROC_MNT
+   request to retrieve the filehandle corresponding to the requested
+   path.
+
+       Client                                       Server
+       ------                                       ------
+
+       -------------- MOUNT port ? -------------->  Portmapper
+       <-------------- Port=984 ------------------
+
+       ------- Filehandle for /export/foo ?  ---->  Mountd @ port 984
+       <--------- Filehandle=0xf82455ce0..  ------
+
+   NFS servers commonly use a client's successful MOUNTPROC_MNT request
+   request as an indication that the client has "mounted" the filesystem
+   and may maintain this information in a file that lists the
+   filesystems that clients currently have mounted.  This information is
+   removed from the file when the client transmits an MOUNTPROC_UMNT
+   request.  Upon receiving a successful reply to a MOUNTPROC_MNT
+   request, a WebNFS client should send a MOUNTPROC_UMNT request to
+   prevent an accumulation of "mounted" records on the server.
+
+   Note that the additional overhead of the PORTMAP and MOUNT protocols
+   will have an effect on the client's binding time to the server and
+   the dynamic port assignment of the MOUNT protocol may preclude easy
+   firewall or proxy server transit.
+
+
+
+Callaghan                    Informational                     [Page 11]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   The client may regain some performance improvement by utilizing a
+   pathname prefix cache.  For instance, if the client already has a
+   filehandle for the pathname "a/b" then there is a good chance that
+   the filehandle for "a/b/c" can be recovered by by a lookup of "c"
+   relative to the filehandle for "a/b", eliminating the need to have
+   the MOUNT protocol translate the pathname.  However, there are risks
+   in doing this.  Since the LOOKUP response provides no indication of
+   filesystem mountpoint crossing on the server, the relative LOOKUP may
+   fail, since NFS requests do not normally cross mountpoints on the
+   server.  The MOUNT service can be relied upon to evaluate the
+   pathname correctly - including the crossing of mountpoints where
+   necessary.
+
+9. Exploiting Concurrency
+
+   NFS servers are known for their high capacity and their
+   responsiveness to clients transmitting multiple concurrent requests.
+   For best performance, a WebNFS client should take advantage of server
+   concurrency. The RPC protocol on which the NFS protocol is based,
+   provides transport-independent support for this concurrency via a
+   unique transaction ID (XID) in every NFS request.
+
+   There is no need for a client to open multiple TCP connections to
+   transmit concurrent requests.  The RPC record marking protocol allows
+   the client to transmit and receive a stream of NFS requests and
+   replies over a single connection.
+
+9.1 Read-ahead
+
+   To keep the number of READ requests to a minimum, a  WebNFS client
+   should use the maximum transfer size that it and the server can
+   support.  The client can often optimize utilization of the link
+   bandwidth by transmitting concurrent READ requests.  The optimum
+   number of READ requests needs to be determined dynamically taking
+   into account the available bandwidth, link latency, and I/O bandwidth
+   of the client and server, e.g.  the following series of READ requests
+   show a client using a single read-ahead to transfer a 128k file from
+   the server with 32k READ requests:
+
+        READ XID=77 offset=0   for 32k  -->
+        READ XID=78 offset=32k for 32k  -->
+                                 <-- Data for XID 77
+        READ XID=79 offset=64k for 32k  -->
+                                 <-- Data for XID 78
+        READ XID=80 offset=96k for 32k  -->
+                                 <-- Data for XID 79
+                                 <-- Data for XID 80
+
+
+
+
+Callaghan                    Informational                     [Page 12]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   The client must be able to handle the return of data out of order.
+   For instance, in the above example the data for XID 78 may be
+   received before the data for XID 77.
+
+   The client should be careful not to use read-ahead beyond the
+   capacity of the server, network, or client, to handle the data. This
+   might be determined by a heuristic that measures throughput as the
+   download proceeds.
+
+9.2 Concurrent File Download
+
+   A client may combine read-ahead with concurrent download of multiple
+   files.  A practical example is that of Web pages that contain
+   multiple images, or a Java Applet that imports multiple class files
+   from the server.
+
+   Omitting read-ahead for clarity, the download of multiple files,
+   "file1", "file2", and "file3" might look something like this:
+
+        LOOKUP XID=77 0x0 "file1"         -->
+        LOOKUP XID=78 0x0 "file2"         -->
+        LOOKUP XID=79 0x0 "file3"         -->
+                                          <-- FH=0x01 for XID 77
+        READ XID=80 0x01 offset=0 for 32k -->
+                                          <-- FH=0x02 for XID 78
+        READ XID=81 0x02 offset=0 for 32k -->
+                                          <-- FH=0x03 for XID 79
+        READ XID=82 0x03 offset=0 for 32k -->
+                                          <-- Data for XID 80
+                                          <-- Data for XID 81
+                                          <-- Data for XID 82
+
+   Note that the replies may be received in a different order from the
+   order in which the requests were transmitted. This is not a problem,
+   since RPC uses the XID to match requests with replies.  A benefit of
+   the request/reply multiplexing provided by the RPC protocol is that
+   the download of a large file that requires many READ requests will
+   not delay the concurrent download of smaller files.
+
+   Again, the client must be careful not to drown the server with
+   download requests.
+
+10.0 Timeout and Retransmission
+
+   A WebNFS client should follow the example of conventional NFS clients
+   and handle server or network outages gracefully.  If a reply is not
+   received within a given timeout, the client should retransmit the
+   request with its original XID (described in Section 8 of RFC 1831).
+
+
+
+Callaghan                    Informational                     [Page 13]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+   The XID can be used by the server to detect duplicate requests and
+   avoid unnecessary work.
+
+   While it would seem that retransmission over a TCP connection is
+   unnecessary (since TCP is responsible for detecting and
+   retransmitting lost data), at the RPC layer retransmission is still
+   required for recovery from a lost TCP connection, perhaps due to a
+   server crash or, because of resource limitations, the server has
+   closed the connection.  When the TCP connection is lost, the client
+   must re-establish the connection and retransmit pending requests.
+
+   The client should set the request timeout according to the following
+   guidelines:
+
+        - A timeout that is too small may result in the
+          wasteful transmission of duplicate requests.
+          The server may be just slow to respond, either because
+          it is heavily loaded, or because the link latency is high.
+
+        - A timeout that is too large may harm throughput if
+          the request is lost and the connection is idle waiting
+          for the retransmission to occur.
+
+        - The optimum timeout may vary with the server's
+          responsiveness over time, and with the congestion
+          and latency of the network.
+
+        - The optimum timeout will vary with the type of NFS
+          request.  For instance, the response to a LOOKUP
+          request will be received more quickly than the response
+          to a READ request.
+
+        - The timeout should be increased according to an
+          exponential backoff until a limit is reached.
+          For instance, if the timeout is 1 second, the
+          first retransmitted request should have a timeout of
+          two seconds, the second retransmission 4 seconds, and
+          so on until the timeout reaches a limit, say 30 seconds.
+          This avoids flooding the network with retransmission
+          requests when the server is down, or overloaded.
+
+   As a general rule of thumb, the client should start with a long
+   timeout until the server's responsiveness is determined.  The timeout
+   can then be set to a value that reflects the server's responsiveness
+   to previous requests.
+
+
+
+
+
+
+Callaghan                    Informational                     [Page 14]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+11.0 Bibliography
+
+   [RFC1808]       Fielding, R.,
+                   "Relative Uniform Resource Locators", RFC 1808,
+                   June 1995.
+                   http://www.internic.net/rfc/rfc1808.txt
+
+   [RFC1831]       Srinivasan, R., "RPC: Remote Procedure Call
+                   Protocol Specification Version 2", RFC 1831,
+                   August 1995.
+                   http://www.internic.net/rfc/rfc1831.txt
+
+   [RFC1832]       Srinivasan, R, "XDR: External Data Representation
+                   Standard", RFC 1832, August 1995.
+                   http://www.internic.net/rfc/rfc1832.txt
+
+   [RFC1833]       Srinivasan, R., "Binding Protocols for ONC RPC
+                   Version 2", RFC 1833, August 1995.
+                   http://www.internic.net/rfc/rfc1833.txt
+
+   [RFC1094]       Sun Microsystems, Inc., "Network Filesystem
+                   Specification", RFC 1094, March 1989.  NFS
+                   version 2 protocol specification.
+                   http://www.internic.net/rfc/rfc1094.txt
+
+   [RFC1813]       Sun Microsystems, Inc., "NFS Version 3 Protocol
+                   Specification," RFC 1813, June 1995.  NFS version
+                   3 protocol specification.
+                   http://www.internic.net/rfc/rfc1813.txt
+
+   [RFC2055]       Callaghan, B., "WebNFS Server Specification",
+                   RFC 2055, October 1996.
+                   http://www.internic.net/rfc/rfc2055.txt
+
+   [Sandberg]      Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh,
+                   B.  Lyon, "Design and Implementation of the Sun
+                   Network Filesystem," USENIX Conference
+                   Proceedings, USENIX Association, Berkeley, CA,
+                   Summer 1985.  The basic paper describing the
+                   SunOS implementation of the NFS version 2
+                   protocol, and discusses the goals, protocol
+                   specification and trade-offs.
+
+   [X/OpenNFS]     X/Open Company, Ltd., X/Open CAE Specification:
+                   Protocols for X/Open Internetworking: XNFS,
+                   X/Open Company, Ltd., Apex Plaza, Forbury Road,
+                   Reading Berkshire, RG1 1AX, United Kingdom,
+                   1991.  This is an indispensable reference for
+
+
+
+Callaghan                    Informational                     [Page 15]
+
+RFC 2054              WebNFS Client Specification           October 1996
+
+
+                   NFS version 2 protocol and accompanying
+                   protocols, including the Lock Manager and the
+                   Portmapper.
+
+   [X/OpenPCNFS]   X/Open Company, Ltd., X/Open CAE Specification:
+                   Protocols for X/Open Internetworking: (PC)NFS,
+                   Developer's Specification, X/Open Company, Ltd.,
+                   Apex Plaza, Forbury Road, Reading Berkshire, RG1
+                   1AX, United Kingdom, 1991.  This is an
+                   indispensable reference for NFS version 2
+                   protocol and accompanying protocols, including
+                   the Lock Manager and the Portmapper.
+
+12. Security Considerations
+
+   Since the WebNFS server features are based on NFS protocol versions 2
+   and 3, the RPC based security considerations described in RFC 1094,
+   RFC 1831, and RFC 1832 apply here also.
+
+   Clients and servers may separately negotiate secure connection
+   schemes for authentication, data integrity, and privacy.
+
+13. Acknowledgements
+
+   This specification was extensively reviewed by the NFS group at
+   SunSoft and brainstormed by Michael Eisler.
+
+14. Author's Address
+
+   Address comments related to this document to:
+
+   nfs@eng.sun.com
+
+
+   Brent Callaghan
+   Sun Microsystems, Inc.
+   2550 Garcia Avenue
+   Mailstop Mpk17-201
+   Mountain View, CA 94043-1100
+
+   Phone: 1-415-786-5067
+   Fax:   1-415-786-5896
+   EMail: brent.callaghan@eng.sun.com
+
+
+
+
+
+
+
+
+Callaghan                    Informational                     [Page 16]
+