RFC 2055
WebNFS Server Specification
RFC 2055: WebNFS Server Specification 🎀
Okay bestie, this one's written by B. Callaghan from Sun Microsystems, Inc. 💖 It's in the Informational category and dates from October 1996. It's part of the Network Working Group series, and the title block doesn't list any RFCs it obsoletes or updates, so it's a standalone doc 🌸
Status of This Memo 📜
This memo is here to give information to the Internet community ✨ It does not specify an Internet standard of any kind, and you can distribute it as much as you like, because distribution is unlimited 🦋
Abstract 💜
Okay so this doc is the spec for a WebNFS server (the thing that answers WebNFS clients) 🖥️ WebNFS extends versions 2 and 3 of the NFS protocols so clients can grab filehandles way more easily, without needing the portmap or MOUNT protocols. Ngl that's the iconic part 👑 Without those protocols in the way, WebNFS clients get faster responses, easy transit through firewalls, and better server scalability. The whole point of this description is to help people build WebNFS servers that actually work together 🫶
Table of Contents 🗂️
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 . . . . . . . . . . . . . . . . . . . . . 101. Introduction 🌈
So NFS is the protocol that lets you access shared filesystems across networks 📁 It's meant to be totally machine-, OS-, network-architecture-, and transport-independent, which is so main character energy ✨ There are two versions right now: version 2 [RFC1094] and version 3 [RFC1813]. Both are built on Sun RPC [RFC1831] and its eXternal Data Representation (XDR) [RFC1832]. This doc assumes you already know your way around NFS and the RPC stuff underneath it 🧚
WebNFS servers add semantic extensions to both NFS versions 💅 The goal is a lightweight binding mechanism for regular clients and web browser clients that need to talk to NFS servers across the Internet. A WebNFS server supports the public filehandle and multi-component lookup features described here, and it also meets some extra requirements 🦋
For a description of WebNFS client requirements, read RFC 2054. 📖
2. TCP vs UDP 🦋
NFS is most famous for using UDP, and honestly UDP does fine on local area networks 🌸 But on wide area networks, where connections are error prone, high-latency, and fighting over bandwidth, TCP is the one everyone respects, because of its congestion control and much better error handling 👑 More and more NFS implementations now support NFS over TCP, so the trend is real 🔥
Here's how a WebNFS client rolls: it always tries a TCP connection to the server first. If the server refuses that connection, the client falls back to UDP 💖 All WebNFS servers SHOULD support client use of TCP, and they MUST support UDP. 🫶
3. Well-known Port 🎀
Internet protocols usually get identified by registered port numbers, but RPC-based protocols are a little different ✨ They register a 32-bit program number, plus a dynamically assigned port, with the portmap service. The portmap service sits on the well-known port 111. Since NFS is RPC-based, NFS servers register their port assignment with portmap 🧚
Here's the tricky part: NFS servers have to re-register at the same port after a crash and recovery. That way clients can recover by just retransmitting an RPC request until they get a response 🙈 That's way simpler than making every client keep checking portmap for a new port. NFS servers usually get this port invariance by using a constant port, 2049, for both UDP and TCP 💜
WebNFS clients skip the portmap step and optimistically assume WebNFS servers are on port 2049. This avoids contacting the server's portmap service, and it makes firewall transit easier too 🦋 Since most NFS servers already use port 2049, that optimism is extremely well justified 💅
A WebNFS server MUST register on UDP port 2049 and TCP port 2049 if TCP is supported. 🌈
4. Server Port Monitoring 💀
Some NFS servers only accept requests from reserved UDP or TCP ports, which means port numbers below 1024. These "privileged" ports are only available to Unix processes with superuser permissions. Requests that don't come from the reserved port range get rejected 🙅♀️ This is kind of an optimistic way of keeping user processes from directly accessing the server and trying to spoof AUTH_UNIX RPC credentials 🔥
WebNFS clients are not required to use reserved ports, so a WebNFS server MUST NOT check the originating port for requests to filesystems made available to WebNFS clients. No port checking for you, WebNFS clients! 🫶
5. Public Filehandle 🌸
The public filehandle is an NFS file handle with a reserved value and special semantics. It lets a client get an initial filehandle in the first place ✨ A WebNFS client can use the public filehandle as that starting point without touching the MOUNT protocol. Since NFS version 2 and version 3 have different filehandle formats, the public filehandle gets defined differently for each one 💖
The public filehandle is a zero filehandle. For NFS version 2, that means a filehandle with 32 zero octets. For version 3, it has zero length 🧚
5.1 Version 2 Public Filehandle 🍓
A version 2 filehandle is defined in RFC1094 as an opaque value that takes up 32 octets. A version 2 public filehandle has a zero in each octet, so it's 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 Version 3 Public Filehandle 🦋
A version 3 filehandle is defined in RFC1813 as a variable-length opaque value that takes up to 64 octets. The length of the filehandle is given by an integer in a 4-octet value, and that integer describes how many valid octets follow it 🌈 A version 3 public filehandle has a length of zero, so it's basically just the length field, sitting there at zero 🫶
+-+-+-+-+
| 0 |
+-+-+-+-+6. Multi-component Lookup 🌸
Normally, an NFS LOOKUP request (versions 2 or 3) takes a directory file handle plus the name of a directory member, and then returns the filehandle of that member ✨ If a client needs to evaluate a pathname with a bunch of components, it starts with the directory file handle for the first component and then issues a series of LOOKUP requests, one component at a time. For instance, evaluating the Unix path "a/b/c" generates separate LOOKUP requests for each component: "a", "b", and "c" 💖
A LOOKUP request that uses the public file handle can give a pathname with multiple components in one go 🔥 The server is expected to evaluate the entire pathname and return a filehandle for the final component. The server is assumed to understand the pathname syntax, but the client MUST NOT make assumptions about that syntax 🙈
A Unix server, for example, uses a slash "/" character to separate components in a Unix pathname 🧚
So instead of evaluating the path "a/b/c" like this:
LOOKUP FH=0x0 "a" --->
<--- FH=0x1
LOOKUP FH=0x1 "b" --->
<--- FH=0x2
LOOKUP FH=0x2 "c" --->
<--- FH=0x3you can replace those three LOOKUP requests, relative to the public filehandle, with one single multi-component lookup:
LOOKUP FH=0x0 "a/b/c" --->
<--- FH=0x3Multi-component lookup is only supported for LOOKUP requests relative to the public filehandle. Lowkey limited, but it's giving focus 💅
6.1 Canonical Path vs. Native Path 🎀
If the pathname in a multi-component LOOKUP request starts with a printable ASCII character, then it MUST be a canonical path. A canonical path is a hierarchically related, slash-separated sequence of components, shaped like <directory>/<directory>/.../<name> 💜
Any "/" character inside a component gets escaped using the escape code %2f. Non-printable ASCII characters (values in the range 00-1F and 7f in hexadecimal) also get escaped, using a "%" character followed by a two-digit hexadecimal code 🌈 And any "%" character that doesn't introduce an encoded character gets encoded itself as %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 isn't a slash, then the path MUST be evaluated relative to the directory the public filehandle is associated with 👑
Not every WebNFS server can handle arbitrary absolute paths, so this part is kind of a vibe check 🙃 The server obviously can't return a filehandle if the path points to a file or directory that the server doesn't export. Also, some servers won't return a filehandle if the path names a file or directory in an exported filesystem that's different from the one tied to the public filehandle 💀
If the first character of the path is 0x80 (non-ASCII), then the character right after it is the first character of a native path. A native path follows the natural pathname syntax of the server. Here are some examples 🧚
Lookup for Canonical Path:
LOOKUP FH=0x0 "/a/b/c"
Lookup for Native Path:
LOOKUP FH=0x0 0x80 "a:b:c"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 doesn't understand, then it MUST return an error to the client: NFSERR_IO for NFS V2, or NFS3ERR_IO for NFS V3. No vibes, just errors 😭
6.2 Symbolic Links 🦋
Servers that support symbolic links may run into pathname components that are symbolic links. The server is expected to evaluate these symbolic links as part of the normal pathname evaluation process 🌸 This is a different semantic from conventional component-at-a-time pathname evaluation by NFS clients, where the client is the one expected to do the evaluating 🙌
However, if the final component is a symbolic link, the server MUST return its filehandle and let the client evaluate it. Hand it back, bestie, and let the client do the work 💅✨
6.3 Export Spanning Pathnames 🌉
Okay so this one is a big deal 👀. The server might evaluate a pathname that points to a file or directory outside the exported hierarchy, either through a multi-component LOOKUP or as a symbolic link sitting inside a pathname. 🔗
Clearly, if the destination of the path isn't in an exported filesystem, the server must return an error to the client. 🙅♀️
Many NFS server implementations rely on the MOUNT protocol to check access to exported filesystems, and the NFS server does no access checking itself. The NFS server treats the filehandle as doing double duty: it identifies a file and acts as a security token 🎟️. WebNFS clients don't normally use the MOUNT protocol, so 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. 😬
Let's look at an example! The server exports two filesystems, and one of them is associated with the public filehandle. 🎀
/export/this (public filehandle)
/export/thatThe 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 NFS server will check the client's use of the filehandle for the destination filesystem. ✨
7. Location of Public Filehandle 📍
A server administrator can associate the public filehandle with any file or directory. For instance, a WebNFS server administrator could attach the public filehandle to the root of an anonymous FTP archive, so that anonymous FTP pathnames could be used to identify files in the FTP hierarchy, e.g.
# share -o ro,public /export/ftpOn 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)
LOOKUP 0x0 "export" (returns an error)
LOOKUP 0x0 "export/foo" (returns an filehandle)8. Index Files 📚
Most HTTP servers support the concept of an index file 🌈. If a browser references a directory that contains an index file, the server returns the contents of the index file rather than a directory listing. For instance, if a browser requests "a/b/c", the server might return the contents of "a/b/c/index.html". 💅
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, 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. ⭐
9. Bibliography 📖
- [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 - [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. 👑
10. Security Considerations 🚨
Okay bestie, this section is SERIOUS 😭 so pay attention!!
Since the WebNFS server features are based on NFS protocol versions 2 and 3, the RPC security considerations described in RFC 1094, RFC 1813, and Appendix A of RFC 1831 apply here also. 🔐
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. ⚠️
11. Acknowledgements 🫶
This specification was extensively reviewed by the NFS group at SunSoft and brainstormed by Michael Eisler. Iconic work, honestly 👑.
12. 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📦 where this page comes from
- ietf: rfc2055 1996-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms