Network Working Group B. Callaghan Request for Comments: 2055 Sun Microsystems, Inc.
Category: Informational October 1996
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.
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 2 2. TCP vs UDP . . . . . . . . . . . . . . . . . . . . . . . 2 3. Well-known Port . . . . . . . . . . . . . . . . . . . . . 2 4. Server Port Monitoring . . . . . . . . . . . . . . . . . . 3 5. Public Filehandle . . . . . . . . . . . . . . . . . . . . 3 5.1 Version 2 Public Filehandle . . . . . . . . . . . . . . 3 5.2 Version 3 Public Filehandle . . . . . . . . . . . . . . 4 6. Multi-component Lookup . . . . . . . . . . . . . . . . . . 4 6.1 Canonical Path vs. Native Path . . . . . . . . . . . . . 5 6.2 Symbolic Links . . . . . . . . . . . . . . . . . . . . . 6 6.3 Export Spanning Pathnames . . . . . . . . . . . . . . . 6 7. Location of Public Filehandle . . . . . . . . . . . . . . 7 8. Index Files . . . . . . . . . . . . . . . . . . . . . . . 7 9. Bibliography . . . . . . . . . . . . . . . . . . . . . . . 8 10. Security Considerations . . . . . . . . . . . . . . . . . 9 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 9 12. Author's Address . . . . . . . . . . . . . . . . . . . . . 10
WebNFS servers implement semantic extensions to both versions of the NFS protocol to support a lightweight binding mechanism for conventional or web browser clients that need to communicate with NFS servers across the Internet. a WebNFS server supports the public filehandle and multi-component lookup features described herein, as well as meeting some additional requirements.
For a description of WebNFS client requirements, read RFC 2054.
A WebNFS client will first attempt to connect to its server with a TCP connection. If the server refuses the connection, the client will attempt to use UDP. All WebNFS servers should support client use of TCP and must support UDP.
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.
A WebNFS server must register on UDP port 2049 and TCP port 2049 if TCP is supported.
Since WebNFS clients are not required to use reserved ports, a WebNFS server must not check the originating port for requests to filesystems made available to WebNFS clients.
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.
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| +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+-+-+-+-+ | 0 | +-+-+-+-+
A LOOKUP request that uses the public file handle can provide a pathname containing multiple components. The server is expected to evaluate the entire pathname and return a filehandle for the final component. The pathname syntax is assumed to be understood by the server, but the client must not make assumptions of the pathname syntax.
A Unix server, for instance, uses a slash "/" character to separate components in a Unix pathname.
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.
of components, <directory>/<directory>/.../<name>.
Occurrences of the "/" character within a component will be escaped using the escape code %2f. Non-printable ascii characters (with values in the range 00-1F and 7f hexadecimal) will also be escaped using the "%" character to introduce a two digit hexadecimal code. Occurrences of the "%" character that do not introduce an encoded character will themselves be encoded with %25.
If the first character of a canonical path is a slash, then the canonical path must be evaluated relative to the server's root directory. If the first character is not a slash, then the path must 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 natural pathname syntax of the server. For example:
Other introductory characters in the range 0x81 - 0xff may be added in future specifications. If the server receives any character in this range that it does not understand then it must return an error to the client: NFSERR_IO for NFS V2, NFS3ERR_IO for NFS V3.
However, if the final component is a symbolic link, the server must return its filehandle and let the client evaluate it.
Clearly, if the destination of the path is not in an exported filesystem, then the server must return an error to the client.
Many NFS server implementations rely on the MOUNT protocol for checking access to exported filesystems and NFS server does no access checking. The NFS server assumes that the filehandle does double duty: identifying a file as well as being a security token. Since WebNFS clients do not normally use the MOUNT protocol, a server that relies on MOUNT checking cannot automatically grant access to another exported filesystem at the destination of a spanning path. These servers must return an error.
For example: the server exports two filesystems. One is associated with the public filehandle.
/export/this (public filehandle)
/export/that
The server receives a LOOKUP request with the public filehandle that identifies a file or directory in the other exported filesystem:
LOOKUP 0x0 "../that/file" or LOOKUP 0x0 "/export/that/file"
Even though the pathname destination is in an exported filesystem, the server cannot return a filehandle without an assurance that the client's use of this filehandle will be authorized.
Servers that check client access to an export on every NFS request have more flexibility. These servers can return filehandles for paths that span exports since the client's use of the filehandle for the destination filesystem will be checked by the NFS server.
# share -o ro,public /export/ftp
On servers that support spanning paths, the public filehandle need not necessarily be attached to an exported directory, though a successful LOOKUP relative to the public filehandle must identify a file or directory that is exported.
For instance, if an NFS server exports a directory "/export/foo" and the public filehandle is attached to the server's root directory, then a LOOKUP of "export/foo" relative to the public filehandle will return a valid file handle but a LOOKUP of "export" will return an access error since the server's "/export" directory is not exported.
/ (public filehandle is here)/\
/ \ / export (not exported) / /\ / / \ / / foo (exported)
A WebNFS server may choose to emulate this feature for the benefit of clients using the NFS protocol to browse a Web hierarchy. On receiving a multi-component lookup for a canonical path that names a directory, the server can check that directory for the presence of an index file. If the file exists then the server may choose to return the filehandle of the index file instead of the directory. Index files are commonly called "index.html" though the name is usually configurable.
[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
[RFC2054] Callaghan, B., "WebNFS Client Specification", RFC 2054, October 1996. http://www.internic.net/rfc/rfc2054.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 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.
Clients and servers may separately negotiate secure connection schemes for authentication, data integrity, and privacy.
Implementors must note carefully the implications of export spanning pathnames as described in section 6.3.
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