home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / rfc / rfc2055 < prev    next >
Text File  |  1996-10-31  |  20KB  |  564 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                       B. Callaghan
  8. Request for Comments: 2055                        Sun Microsystems, Inc.
  9. Category: Informational                                     October 1996
  10.  
  11.  
  12.                       WebNFS Server Specification
  13.  
  14. Status of this Memo
  15.  
  16.    This memo provides information for the Internet community.  This memo
  17.    does not specify an Internet standard of any kind.  Distribution of
  18.    this memo is unlimited.
  19.  
  20. Abstract
  21.  
  22.    This document describes the specifications for a server of WebNFS
  23.    clients.  WebNFS extends the semantics of versions 2 and 3 of the NFS
  24.    protocols to allow clients to obtain filehandles more easily, without
  25.    recourse to the portmap or MOUNT protocols.  In removing the need for
  26.    these protocols, WebNFS clients see benefits in faster response to
  27.    requests, easy transit of firewalls and better server scalability
  28.    This description is provided to facilitate compatible implementations
  29.    of WebNFS servers.
  30.  
  31. Table of Contents
  32.  
  33.    1.    Introduction . . . . . . . . . . . . . . . . . . . . . . . 2
  34.    2.    TCP vs UDP . . . . . . . . . . . . .   . . . . . . . . . . 2
  35.    3.    Well-known Port  . . . . . . . . . . . . . . . . . . . . . 2
  36.    4.    Server Port Monitoring . . . . . . . . . . . . . . . . . . 3
  37.    5.    Public Filehandle  . . . . . . . . . . . . . . . . . . . . 3
  38.    5.1     Version 2 Public Filehandle  . . . . . . . . . . . . . . 3
  39.    5.2     Version 3 Public Filehandle  . . . . . . . . . . . . . . 4
  40.    6.    Multi-component Lookup . . . . . . . . . . . . . . . . . . 4
  41.    6.1     Canonical Path vs. Native Path . . . . . . . . . . . . . 5
  42.    6.2     Symbolic Links . . . . . . . . . . . . . . . . . . . . . 6
  43.    6.3     Export Spanning Pathnames  . . . . . . . . . . . . . . . 6
  44.    7.    Location of Public Filehandle  . . . . . . . . . . . . . . 7
  45.    8.    Index Files  . . . . . . . . . . . . . . . . . . . . . . . 7
  46.    9.    Bibliography . . . . . . . . . . . . . . . . . . . . . . . 8
  47.    10.   Security Considerations  . . . . . . . . . . . . . . . . . 9
  48.    11.   Acknowledgements . . . . . . . . . . . . . . . . . . . . . 9
  49.    12.   Author's Address . . . . . . . . . . . . . . . . . . . . . 10
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. Callaghan                    Informational                      [Page 1]
  59.  
  60. RFC 2055              WebNFS Server Specification           October 1996
  61.  
  62.  
  63. 1. Introduction
  64.  
  65.    The NFS protocol provides access to shared filesystems across
  66.    networks.  It is intended to be machine, operating system, network
  67.    architecture, and transport independent.  The protocol currently
  68.    exists in two versions: version 2 [RFC1094] and version 3 [RFC1813],
  69.    both built on Sun RPC [RFC1831] and its associated eXternal Data
  70.    Representation (XDR) [RFC1832]. This document assumes some
  71.    familiarity with the NFS protocol and underlying RPC protocols.
  72.  
  73.    WebNFS servers implement semantic extensions to both versions of the
  74.    NFS protocol to support a lightweight binding mechanism for
  75.    conventional or web browser clients that need to communicate with NFS
  76.    servers across the Internet. a WebNFS server supports the public
  77.    filehandle and multi-component lookup features described herein, as
  78.    well as meeting some additional requirements.
  79.  
  80.    For a description of WebNFS client requirements, read RFC 2054.
  81.  
  82. 2. TCP vs UDP
  83.  
  84.    The NFS protocol is most well known for its use of UDP which performs
  85.    acceptably on local area networks.  However, on wide area networks
  86.    with error prone, high-latency connections and bandwidth contention,
  87.    TCP is well respected for its congestion control and superior error
  88.    handling.  A growing number of NFS implementations now support the
  89.    NFS protocol over TCP connections.
  90.  
  91.    A WebNFS client will first attempt to connect to its server with a
  92.    TCP connection.  If the server refuses the connection, the client
  93.    will attempt to use UDP.  All WebNFS servers should support client
  94.    use of TCP and must support UDP.
  95.  
  96. 3. Well-known Port
  97.  
  98.    While Internet protocols are generally identified by registered port
  99.    number assignments, RPC based protocols register a 32 bit program
  100.    number and a dynamically assigned port with the portmap service which
  101.    is registered on the well-known port 111.  Since the NFS protocol is
  102.    RPC-based, NFS servers register their port assignment with the
  103.    portmap service.
  104.  
  105.    NFS servers are constrained by a requirement to re-register at the
  106.    same port after a server crash and recovery so that clients can
  107.    recover simply by retransmitting an RPC request until a response is
  108.    received.  This is simpler than the alternative of having the client
  109.    repeatedly check with the portmap service for a new port assignment.
  110.    NFS servers typically achieve this port invariance by registering a
  111.  
  112.  
  113.  
  114. Callaghan                    Informational                      [Page 2]
  115.  
  116. RFC 2055              WebNFS Server Specification           October 1996
  117.  
  118.  
  119.    constant port assignment, 2049, for both UDP and TCP.
  120.  
  121.    To avoid the overhead of contacting the server's portmap service, and
  122.    to facilitate transit through packet filtering firewalls, WebNFS
  123.    clients optimistically assume that WebNFS servers register on port
  124.    2049.  Most NFS servers use this port assignment already, so this
  125.    client optimism is well justified.
  126.  
  127.    A WebNFS server must register on UDP port 2049 and TCP port 2049 if
  128.    TCP is supported.
  129.  
  130. 4. Server Port Monitoring
  131.  
  132.    Some NFS servers accept requests only from reserved UDP or TCP ports,
  133.    i.e. port numbers below 1024.  These "privileged" ports are available
  134.    only to Unix processes with superuser permissions.  Requests that do
  135.    not originate from the range of reserved ports are rejected.  This an
  136.    optimistic way of preventing direct access to the server from user
  137.    processes that may attempt to spoof AUTH_UNIX RPC credentials.
  138.  
  139.    Since WebNFS clients are not required to use reserved ports, a WebNFS
  140.    server must not check the originating port for requests to
  141.    filesystems made available to WebNFS clients.
  142.  
  143. 5. Public Filehandle
  144.  
  145.    The public filehandle is an NFS file handle with a reserved value and
  146.    special semantics that allow an initial filehandle to be obtained.  A
  147.    WebNFS client can use the public filehandle as an initial filehandle
  148.    without using the MOUNT protocol.  Since NFS version 2 and version 3
  149.    have different filehandle formats, the public filehandle is defined
  150.    differently for each.
  151.  
  152.    The public filehandle is a zero filehandle.  For NFS version 2 this
  153.    is a filehandle with 32 zero octets.  A version 3 public filehandle
  154.    has zero length.
  155.  
  156. 5.1 Version 2 Public Filehandle
  157.  
  158.    A version 2 filehandle is defined in RFC1094 as an opaque value
  159.    occupying 32 octets.  A version 2 public filehandle has a zero in
  160.    each octet, i.e. all zeros.
  161.  
  162.     1                                                             32
  163.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  164.    |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|
  165.    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  166.  
  167.  
  168.  
  169.  
  170. Callaghan                    Informational                      [Page 3]
  171.  
  172. RFC 2055              WebNFS Server Specification           October 1996
  173.  
  174.  
  175. 5.2 Version 3 Public Filehandle
  176.  
  177.    A version 3 filehandle is defined in RFC1813 as a variable length
  178.    opaque value occupying up to 64 octets.  The length of the filehandle
  179.    is indicated by an integer value contained in a 4 octet value which
  180.    describes the number of valid octets that follow. A version 3 public
  181.    filehandle has a length of zero.
  182.  
  183.    +-+-+-+-+
  184.    |   0   |
  185.    +-+-+-+-+
  186.  
  187. 6. Multi-component Lookup
  188.  
  189.    Normally the NFS LOOKUP request (versions 2 or 3) takes a directory
  190.    file handle along with the name of a directory member, and returns
  191.    the filehandle of the directory member.  If a client needs to
  192.    evaluate a pathname that contains a sequence of components, then
  193.    beginning with the directory file handle of the first component it
  194.    must issue a series of LOOKUP requests one component at a time.  For
  195.    instance, evaluation of the Unix path "a/b/c" will generate separate
  196.    LOOKUP requests for each component of the pathname "a", "b", and "c".
  197.  
  198.    A LOOKUP request that uses the public file handle can provide a
  199.    pathname containing multiple components.  The server is expected to
  200.    evaluate the entire pathname and return a filehandle for the final
  201.    component. The pathname syntax is assumed to be understood by the
  202.    server, but the client must not make assumptions of the pathname
  203.    syntax.
  204.  
  205.    A Unix server, for instance, uses a slash "/" character to separate
  206.    components in a Unix pathname.
  207.  
  208.    For example, rather than evaluate the path "a/b/c" as:
  209.  
  210.         LOOKUP  FH=0x0  "a"  --->
  211.                              <---  FH=0x1
  212.         LOOKUP  FH=0x1  "b"  --->
  213.                              <---  FH=0x2
  214.         LOOKUP  FH=0x2  "c"  --->
  215.                              <---  FH=0x3
  216.  
  217.    Relative to the public filehandle these three LOOKUP requests can be
  218.    replaced by a single multi-component lookup:
  219.  
  220.         LOOKUP  FH=0x0  "a/b/c"  --->
  221.                                  <---  FH=0x3
  222.  
  223.  
  224.  
  225.  
  226. Callaghan                    Informational                      [Page 4]
  227.  
  228. RFC 2055              WebNFS Server Specification           October 1996
  229.  
  230.  
  231.    Multi-component lookup is supported only for LOOKUP requests relative
  232.    to the public filehandle.
  233.  
  234. 6.1 Canonical Path vs. Native Path
  235.  
  236.    If the pathname in a multi-component LOOKUP request begins with a
  237.    printable ASCII character, then it must be a canonical path.  A
  238.    canonical path is a hierarchically-related, slash-separated sequence
  239.    of components, <directory>/<directory>/.../<name>.
  240.  
  241.    Occurrences of the "/" character within a component will be escaped
  242.    using the escape code %2f.  Non-printable ascii characters (with
  243.    values in the range 00-1F and 7f hexadecimal) will also be escaped
  244.    using the "%" character to introduce a two digit hexadecimal code.
  245.    Occurrences of the "%" character that do not introduce an encoded
  246.    character will themselves be encoded with %25.
  247.  
  248.    If the first character of a canonical path is a slash, then the
  249.    canonical path must be evaluated relative to the server's root
  250.    directory.  If the first character is not a slash, then the path must
  251.    be evaluated relative to the directory with which the public
  252.    filehandle is associated.
  253.  
  254.    Not all WebNFS servers can support arbitrary use of absolute paths.
  255.    Clearly, the server cannot return a filehandle if the path identifies
  256.    a file or directory that is not exported by the server.  In addition,
  257.    some servers will not return a filehandle if the path names a file or
  258.    directory in an exported filesystem different from the one that is
  259.    associated with the public filehandle.
  260.  
  261.    If the first character of the path is 0x80 (non-ascii) then the
  262.    following character is the first in a native path.  A native path
  263.    conforms to the natural pathname syntax of the server. For example:
  264.  
  265.         Lookup for Canonical Path:
  266.  
  267.                 LOOKUP FH=0x0 "/a/b/c"
  268.  
  269.         Lookup for Native Path:
  270.  
  271.                 LOOKUP FH=0x0  0x80 "a:b:c"
  272.  
  273.    Other introductory characters in the range 0x81 - 0xff may be added
  274.    in future specifications.  If the server receives any character in
  275.    this range that it does not understand then it must return an error
  276.    to the client: NFSERR_IO for NFS V2, NFS3ERR_IO for NFS V3.
  277.  
  278.  
  279.  
  280.  
  281.  
  282. Callaghan                    Informational                      [Page 5]
  283.  
  284. RFC 2055              WebNFS Server Specification           October 1996
  285.  
  286.  
  287. 6.2 Symbolic Links
  288.  
  289.    Servers that support symbolic links may encounter pathname components
  290.    that are symbolic links.  The server is expected to evaluate these
  291.    symbolic links as a part of the normal pathname evaluation process.
  292.    This is a different semantic from that of conventional component-at-
  293.    a-time pathname evaluation by NFS clients, where the client is
  294.    expected to do the evaluation.
  295.  
  296.    However, if the final component is a symbolic link, the server must
  297.    return its filehandle and let the client evaluate it.
  298.  
  299. 6.3 Export Spanning Pathnames
  300.  
  301.    The server may evaluate a pathname, either through a multi-component
  302.    LOOKUP or as a symbolic link embedded in a pathname, that references
  303.    a file or directory outside of the exported hierarchy.
  304.  
  305.    Clearly, if the destination of the path is not in an exported
  306.    filesystem, then the server must return an error to the client.
  307.  
  308.    Many NFS server implementations rely on the MOUNT protocol for
  309.    checking access to exported filesystems and NFS server does no access
  310.    checking.  The NFS server assumes that the filehandle does double
  311.    duty: identifying a file as well as being a security token. Since
  312.    WebNFS clients do not normally use the MOUNT protocol, a server that
  313.    relies on MOUNT checking cannot automatically grant access to another
  314.    exported filesystem at the destination of a spanning path. These
  315.    servers must return an error.
  316.  
  317.    For example: the server exports two filesystems.  One is associated
  318.    with the public filehandle.
  319.  
  320.       /export/this   (public filehandle)
  321.  
  322.       /export/that
  323.  
  324.    The server receives a LOOKUP request with the public filehandle that
  325.    identifies a file or directory in the other exported filesystem:
  326.  
  327.       LOOKUP 0x0  "../that/file"
  328.    or
  329.       LOOKUP 0x0  "/export/that/file"
  330.  
  331.    Even though the pathname destination is in an exported filesystem,
  332.    the server cannot return a filehandle without an assurance that the
  333.    client's use of this filehandle will be authorized.
  334.  
  335.  
  336.  
  337.  
  338. Callaghan                    Informational                      [Page 6]
  339.  
  340. RFC 2055              WebNFS Server Specification           October 1996
  341.  
  342.  
  343.    Servers that check client access to an export on every NFS request
  344.    have more flexibility.  These servers can return filehandles for
  345.    paths that span exports since the client's use of the filehandle for
  346.    the destination filesystem will be checked by the NFS server.
  347.  
  348. 7. Location of Public Filehandle
  349.  
  350.    A server administrator can associate the public filehandle with any
  351.    file or directory. For instance, a WebNFS server administrator could
  352.    attach the public filehandle to the root of an anonymous FTP archive,
  353.    so that anonymous FTP pathnames could be used to identify files in
  354.    the FTP hierarchy, e.g.
  355.  
  356.       # share -o ro,public  /export/ftp
  357.  
  358.    On servers that support spanning paths, the public filehandle need
  359.    not necessarily be attached to an exported directory, though a
  360.    successful LOOKUP relative to the public filehandle must identify a
  361.    file or directory that is exported.
  362.  
  363.    For instance, if an NFS server exports a directory "/export/foo" and
  364.    the public filehandle is attached to the server's root directory,
  365.    then a LOOKUP of "export/foo" relative to the public filehandle will
  366.    return a valid file handle but a LOOKUP of "export" will return an
  367.    access error since the server's "/export" directory is not exported.
  368.  
  369.                /            (public filehandle is here)
  370.               /\
  371.              /  \
  372.             /   export      (not exported)
  373.            /    /\
  374.           /    /  \
  375.          /    /   foo       (exported)
  376.  
  377.  
  378.       LOOKUP 0x0  "export"      (returns an error)
  379.  
  380.       LOOKUP 0x0  "export/foo"  (returns an filehandle)
  381.  
  382. 8. Index Files
  383.  
  384.    Most HTTP servers support the concept of an index file.  If a browser
  385.    references a directory that contains an index file, then the server
  386.    will return the contents of the index file rather than a directory
  387.    listing.  For instance if a browser requests "a/b/c" then the server
  388.    might return the contents of "a/b/c/index.html".
  389.  
  390.  
  391.  
  392.  
  393.  
  394. Callaghan                    Informational                      [Page 7]
  395.  
  396. RFC 2055              WebNFS Server Specification           October 1996
  397.  
  398.  
  399.    A WebNFS server may choose to emulate this feature for the benefit of
  400.    clients using the NFS protocol to browse a Web hierarchy. On
  401.    receiving a multi-component lookup for a canonical path that names a
  402.    directory, the server can check that directory for the presence of an
  403.    index file.  If the file exists then the server may choose to return
  404.    the filehandle of the index file instead of the directory.  Index
  405.    files are commonly called "index.html" though the name is usually
  406.    configurable.
  407.  
  408. 9. Bibliography
  409.  
  410.    [RFC1831]       Srinivasan, R., "RPC: Remote Procedure Call
  411.                    Protocol Specification Version 2", RFC 1831,
  412.                    August 1995.
  413.                    http://www.internic.net/rfc/rfc1831.txt
  414.  
  415.    [RFC1832]       Srinivasan, R., "XDR: External Data Representation
  416.                    Standard," RFC 1832, August 1995.
  417.                    http://www.internic.net/rfc/rfc1832.txt
  418.  
  419.    [RFC1833]       Srinivasan, R., "Binding Protocols for ONC RPC
  420.                    Version 2", RFC 1833, August 1995.
  421.                    http://www.internic.net/rfc/rfc1833.txt
  422.  
  423.    [RFC1094]       Sun Microsystems, Inc., "Network Filesystem
  424.                    Specification", RFC 1094, March 1989.  NFS
  425.                    version 2 protocol specification.
  426.                    http://www.internic.net/rfc/rfc1094.txt
  427.  
  428.    [RFC1813]       Sun Microsystems, Inc., "NFS Version 3 Protocol
  429.                    Specification", RFC 1813, June 1995.  NFS version
  430.                    3 protocol specification.
  431.                    http://www.internic.net/rfc/rfc1813.txt
  432.  
  433.    [RFC2054]       Callaghan, B., "WebNFS Client Specification",
  434.                    RFC 2054, October 1996.
  435.                    http://www.internic.net/rfc/rfc2054.txt
  436.  
  437.    [Sandberg]      Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh,
  438.                    B.  Lyon, "Design and Implementation of the Sun
  439.                    Network Filesystem," USENIX Conference
  440.                    Proceedings, USENIX Association, Berkeley, CA,
  441.                    Summer 1985.  The basic paper describing the
  442.                    SunOS implementation of the NFS version 2
  443.                    protocol, and discusses the goals, protocol
  444.                    specification and trade-offs.
  445.  
  446.  
  447.  
  448.  
  449.  
  450. Callaghan                    Informational                      [Page 8]
  451.  
  452. RFC 2055              WebNFS Server Specification           October 1996
  453.  
  454.  
  455.    [X/OpenNFS]     X/Open Company, Ltd., X/Open CAE Specification:
  456.                    Protocols for X/Open Internetworking: XNFS,
  457.                    X/Open Company, Ltd., Apex Plaza, Forbury Road,
  458.                    Reading Berkshire, RG1 1AX, United Kingdom,
  459.                    1991.  This is an indispensable reference for
  460.                    NFS version 2 protocol and accompanying
  461.                    protocols, including the Lock Manager and the
  462.                    Portmapper.
  463.  
  464.    [X/OpenPCNFS]   X/Open Company, Ltd., X/Open CAE Specification:
  465.                    Protocols for X/Open Internetworking: (PC)NFS,
  466.                    Developer's Specification, X/Open Company, Ltd.,
  467.                    Apex Plaza, Forbury Road, Reading Berkshire, RG1
  468.                    1AX, United Kingdom, 1991.  This is an
  469.                    indispensable reference for NFS version 2
  470.                    protocol and accompanying protocols, including
  471.                    the Lock Manager and the Portmapper.
  472.  
  473. 10. Security Considerations
  474.  
  475.    Since the WebNFS server features are based on NFS protocol versions 2
  476.    and 3, the RPC security considerations described in RFC 1094, RFC
  477.    1813, and Appendix A of RFC 1831 apply here also.
  478.  
  479.    Clients and servers may separately negotiate secure connection
  480.    schemes for authentication, data integrity, and privacy.
  481.  
  482.    Implementors must note carefully the implications of export spanning
  483.    pathnames as described in section 6.3.
  484.  
  485. 11. Acknowledgements
  486.  
  487.    This specification was extensively reviewed by the NFS group at
  488.    SunSoft and brainstormed by Michael Eisler.
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506. Callaghan                    Informational                      [Page 9]
  507.  
  508. RFC 2055              WebNFS Server Specification           October 1996
  509.  
  510.  
  511. 12. Author's Address
  512.  
  513.    Address comments related to this document to:
  514.  
  515.    nfs@eng.sun.com
  516.  
  517.  
  518.    Brent Callaghan
  519.    Sun Microsystems, Inc.
  520.    2550 Garcia Avenue
  521.    Mailstop Mpk17-201
  522.    Mountain View, CA 94043-1100
  523.  
  524.    Phone: 1-415-786-5067
  525.    Fax:   1-415-786-5896
  526.    EMail: brent.callaghan@eng.sun.com
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Callaghan                    Informational                     [Page 10]
  563.  
  564.