idnits 2.17.1 draft-callaghan-webnfs-server-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 481 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 2 instances of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 1996) is 10055 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Missing reference section? 'RFC1094' on line 371 looks like a reference -- Missing reference section? 'RFC1813' on line 378 looks like a reference -- Missing reference section? 'RFC1831' on line 358 looks like a reference -- Missing reference section? 'RFC1832' on line 363 looks like a reference -- Missing reference section? 'RFC1833' on line 367 looks like a reference -- Missing reference section? 'RFCmmmm' on line 385 looks like a reference -- Missing reference section? 'Sandberg' on line 389 looks like a reference Summary: 8 errors (**), 0 flaws (~~), 1 warning (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group B. Callaghan 2 INTERNET DRAFT 3 Category: Informational 4 Expire in six months Sun Microsystems, Inc. 5 October 1996 7 WebNFS Server Specification 8 10 Abstract 12 This document describes the specifications for a server of 13 WebNFS clients. WebNFS extends the semantics of versions 2 14 and 3 of the NFS protocols to allow clients to obtain 15 filehandles more easily, without recourse to the portmap or 16 MOUNT protocols. In removing the need for these protocols, 17 WebNFS clients see benefits in faster response to requests, 18 easy transit of firewalls and better server scalability This 19 description is provided to facilitate compatible 20 implementations of WebNFS servers. 22 Status of this Memo 24 This memo provides information for the Internet community. 25 This memo does not specify an Internet standard of any kind. 26 Distribution of this memo is unlimited. 28 Table of Contents 30 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 2 31 2. TCP vs UDP . . . . . . . . . . . . . . . . . . . . . . . 2 32 3. Well-known Port . . . . . . . . . . . . . . . . . . . . . 2 33 4. Server Port Monitoring . . . . . . . . . . . . . . . . . . 3 34 5. Public Filehandle . . . . . . . . . . . . . . . . . . . . 3 35 5.1 Version 2 Public Filehandle . . . . . . . . . . . . . . 3 36 5.2 Version 3 Public Filehandle . . . . . . . . . . . . . . 4 37 6. Multi-component Lookup . . . . . . . . . . . . . . . . . . 4 38 6.1 Canonical Path vs. Native Path . . . . . . . . . . . . . 5 39 6.2 Symbolic Links . . . . . . . . . . . . . . . . . . . . . 6 40 6.3 Export Spanning Pathnames . . . . . . . . . . . . . . . 6 41 7. Location of Public Filehandle . . . . . . . . . . . . . . 7 42 8. Index Files . . . . . . . . . . . . . . . . . . . . . . . 8 43 9. Bibliography . . . . . . . . . . . . . . . . . . . . . . . 8 44 10. Security Considerations . . . . . . . . . . . . . . . . . 9 45 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 10 46 12. Author's Address . . . . . . . . . . . . . . . . . . . . . 10 48 1. Introduction 50 The NFS protocol provides access to shared filesystems across 51 networks. It is intended to be machine, operating system, network 52 architecture, and transport independent. The protocol currently 53 exists in two versions: version 2 [RFC1094] and version 3 54 [RFC1813], both built on Sun RPC [RFC1831] and its associated 55 eXternal Data Representation (XDR) [RFC1832]. This document 56 assumes some familiarity with the NFS protocol and underlying RPC 57 protocols. 59 WebNFS servers implement semantic extensions to both versions 60 of the NFS protocol to support a lightweight binding mechanism 61 for conventional or web browser clients that need to communicate 62 with NFS servers across the Internet. a WebNFS server supports 63 the public filehandle and multi-component lookup features 64 described herein, as well as meeting some additional requirements. 66 For a description of WebNFS client requirements, read RFC mmmm. 68 2. TCP vs UDP 70 The NFS protocol is most well known for its use of UDP which 71 performs acceptably on local area networks. However, on wide area 72 networks with error prone, high-latency connections and bandwidth 73 contention, TCP is well respected for its congestion control and 74 superior error handling. A growing number of NFS implementations 75 now support the NFS protocol over TCP connections. 77 A WebNFS client will first attempt to connect to its server 78 with a TCP connection. If the server refuses the connection, 79 the client will attempt to use UDP. All WebNFS servers should 80 support client use of TCP and must support UDP. 82 3. Well-known Port 84 While Internet protocols are generally identified by registered 85 port number assignments, RPC based protocols register a 32 bit 86 program number and a dynamically assigned port with the portmap 87 service which is registered on the well-known port 111. Since 88 the NFS protocol is RPC-based, NFS servers register their port 89 assignment with the portmap service. 91 NFS servers are constrained by a requirement to re-register 92 at the same port after a server crash and recovery so that 93 clients can recover simply by retransmitting an RPC request 94 until a response is received. This is simpler than the 95 alternative of having the client repeatedly check with 96 the portmap service for a new port assignment. NFS servers 97 typically achieve this port invariance by registering a 98 constant port assignment, 2049, for both UDP and TCP. 100 To avoid the overhead of contacting the server's portmap 101 service, and to facilitate transit through packet filtering 102 firewalls, WebNFS clients optimistically assume that WebNFS 103 servers register on port 2049. Most NFS servers use this 104 port assignment already, so this client optimism is well 105 justified. 107 A WebNFS server must register on UDP port 2049 and TCP 108 port 2049 if TCP is supported. 110 4. Server Port Monitoring 112 Some NFS servers accept requests only from reserved UDP or TCP 113 ports, i.e. port numbers below 1024. These "privileged" ports 114 are available only to Unix processes with superuser permissions. 115 Requests that do not originate from the range of reserved ports 116 are rejected. This an optimistic way of preventing direct 117 access to the server from user processes that may attempt to 118 spoof AUTH_UNIX RPC credentials. 120 Since WebNFS clients are not required to use reserved ports, 121 a WebNFS server must not check the originating port for 122 requests to filesystems made available to WebNFS clients. 124 5. Public Filehandle 126 The public filehandle is an NFS file handle with a reserved value 127 and special semantics that allow an initial filehandle to be 128 obtained. A WebNFS client can use the public filehandle as an 129 initial filehandle without using the MOUNT protocol. Since NFS 130 version 2 and version 3 have different filehandle formats, the 131 public filehandle is defined differently for each. 133 The public filehandle is a zero filehandle. For NFS version 2 134 this is a filehandle with 32 zero octets. A version 3 public 135 filehandle has zero length. 137 5.1 Version 2 Public Filehandle 139 A version 2 filehandle is defined in RFC1094 as an opaque value 140 occupying 32 octets. A version 2 public filehandle has a zero 141 in each octet, i.e. all zeros. 143 1 32 144 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 145 |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| 146 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 148 5.2 Version 3 Public Filehandle 150 A version 3 filehandle is defined in RFC1813 as a variable length 151 opaque value occupying up to 64 octets. The length of the filehandle 152 is indicated by an integer value contained in a 4 octet value 153 which describes the number of valid octets that follow. A version 154 3 public filehandle has a length of zero. 156 +-+-+-+-+ 157 | 0 | 158 +-+-+-+-+ 160 6. Multi-component Lookup 162 Normally the NFS LOOKUP request (versions 2 or 3) takes a 163 directory file handle along with the name of a directory member, 164 and returns the filehandle of the directory member. If a client 165 needs to evaluate a pathname that contains a sequence of 166 components, then beginning with the directory file handle of the 167 first component it must issue a series of LOOKUP requests one 168 component at a time. For instance, evaluation of the Unix path 169 "a/b/c" will generate separate LOOKUP requests for each component 170 of the pathname "a", "b", and "c". 172 A LOOKUP request that uses the public file handle can provide a 173 pathname containing multiple components. The server is expected 174 to evaluate the entire pathname and return a filehandle for the 175 final component. The pathname syntax is assumed to be understood 176 by the server, but the client must not make assumptions of the 177 pathname syntax. 179 A Unix server, for instance, uses a slash "/" character to 180 separate components in a Unix pathname. 182 For example, rather than evaluate the path "a/b/c" as: 184 LOOKUP FH=0x0 "a" ---> 185 <--- FH=0x1 186 LOOKUP FH=0x1 "b" ---> 187 <--- FH=0x2 188 LOOKUP FH=0x2 "c" ---> 189 <--- FH=0x3 191 Relative to the public filehandle these three LOOKUP 192 requests can be replaced by a single multi-component 193 lookup: 195 LOOKUP FH=0x0 "a/b/c" ---> 196 <--- FH=0x3 198 Multi-component lookup is supported only for LOOKUP 199 requests relative to the public filehandle. 201 6.1 Canonical Path vs. Native Path 203 If the pathname in a multi-component LOOKUP request begins with a 204 printable ASCII character, then it must be a canonical path. 205 A canonical path is a hierarchically-related, slash-separated 206 sequence of components, //.../. 208 Occurrences of the "/" character within a component will be 209 escaped using the escape code %2f. Non-printable ascii characters 210 (with values in the range 00-1F and 7f hexadecimal) will also be 211 escaped using the "%" character to introduce a two digit 212 hexadecimal code. Occurrences of the "%" character that do not 213 introduce an encoded character will themselves be encoded with %25. 215 If the first character of a canonical path is a slash, then the 216 canonical path must be evaluated relative to the server's root 217 directory. If the first character is not a slash, then the path 218 must be evaluated relative to the directory with which the public 219 filehandle is associated. 221 Not all WebNFS servers can support arbitrary use of absolute 222 paths. Clearly, the server cannot return a filehandle if the path 223 identifies a file or directory that is not exported by the 224 server. In addition, some servers will not return a filehandle if 225 the path names a file or directory in an exported filesystem 226 different from the one that is associated with the public 227 filehandle. 229 If the first character of the path is 0x80 (non-ascii) then the 230 following character is the first in a native path. A native path 231 conforms to the natural pathname syntax of the server. For 232 example: 234 Lookup for Canonical Path: 236 LOOKUP FH=0x0 "/a/b/c" 238 Lookup for Native Path: 240 LOOKUP FH=0x0 0x80 "a:b:c" 242 Other introductory characters in the range 0x81 - 0xff may 243 be added in future specifications. If the server receives 244 any character in this range that it does not understand then 245 it must return an error to the client: NFSERR_IO for NFS V2, 246 NFS3ERR_IO for NFS V3. 248 6.2 Symbolic Links 250 Servers that support symbolic links may encounter pathname 251 components that are symbolic links. The server is expected 252 to evaluate these symbolic links as a part of the normal 253 pathname evaluation process. This is a different semantic 254 from that of conventional component-at-a-time pathname evaluation 255 by NFS clients, where the client is expected to do the evaluation. 257 However, if the final component is a symbolic link, the server 258 must return its filehandle and let the client evaluate it. 260 6.3 Export Spanning Pathnames 262 The server may evaluate a pathname, either through a multi-component 263 LOOKUP or as a symbolic link embedded in a pathname, that references 264 a file or directory outside of the exported hierarchy. 266 Clearly, if the destination of the path is not in an exported 267 filesystem, then the server must return an error to the client. 269 Many NFS server implementations rely on the MOUNT protocol for 270 checking access to exported filesystems and NFS server does 271 no access checking. The NFS server assumes that the filehandle 272 does double duty: identifying a file as well as being a security 273 token. Since WebNFS clients do not normally use the MOUNT protocol, 274 a server that relies on MOUNT checking cannot automatically grant 275 access to another exported filesystem at the destination of a 276 spanning path. These servers must return an error. 278 For example: the server exports two filesystems. One is 279 associated with the public filehandle. 281 /export/this (public filehandle) 283 /export/that 285 The server receives a LOOKUP request with the public 286 filehandle that identifies a file or directory in the 287 other exported filesystem: 289 LOOKUP 0x0 "../that/file" 290 or 291 LOOKUP 0x0 "/export/that/file" 293 Even though the pathname destination is in an exported filesystem, 294 the server cannot return a filehandle without an assurance that 295 the client's use of this filehandle will be authorized. 297 Servers that check client access to an export on every NFS 298 request have more flexibility. These servers can return 299 filehandles for paths that span exports since the client's 300 use of the filehandle for the destination filesystem will 301 be checked by the NFS server. 303 7. Location of Public Filehandle 305 A server administrator can associate the public filehandle with 306 any file or directory. For instance, a WebNFS server administrator 307 could attach the public filehandle to the root of an anonymous FTP 308 archive, so that anonymous FTP pathnames could be used to identify 309 files in the FTP hierarchy, e.g. 311 # share -o ro,public /export/ftp 313 On servers that support spanning paths, the public filehandle need 314 not necessarily be attached to an exported directory, though a 315 successful LOOKUP relative to the public filehandle must identify 316 a file or directory that is exported. 318 For instance, if an NFS server exports a directory "/export/foo" 319 and the public filehandle is attached to the server's root 320 directory, then a LOOKUP of "export/foo" relative to the public 321 filehandle will return a valid file handle but a LOOKUP of 322 "export" will return an access error since the server's "/export" 323 directory is not exported. 325 / (public filehandle is here) 326 /\ 327 / \ 328 / export (not exported) 329 / /\ 330 / / \ 331 / / foo (exported) 333 LOOKUP 0x0 "export" (returns an error) 335 LOOKUP 0x0 "export/foo" (returns an filehandle) 337 8. Index Files 339 Most HTTP servers support the concept of an index file. 340 If a browser references a directory that contains an 341 index file, then the server will return the contents of 342 the index file rather than a directory listing. 343 For instance if a browser requests "a/b/c" then the 344 server might return the contents of "a/b/c/index.html". 346 A WebNFS server may choose to emulate this feature for 347 the benefit of clients using the NFS protocol to browse 348 a Web hierarchy. On receiving a multi-component lookup 349 for a canonical path that names a directory, the server 350 can check that directory for the presence of an index 351 file. If the file exists then the server may choose to 352 return the filehandle of the index file instead of the 353 directory. Index files are commonly called "index.html" 354 though the name is usually configurable. 356 9. Bibliography 358 [RFC1831] R. Srinivasan, "RPC: Remote Procedure Call 359 Protocol Specification Version 2," RFC-1831, 360 August 1995. 361 http://www.internic.net/rfc/rfc1831.txt 363 [RFC1832] R. Srinivasan, "XDR: External Data Representation 364 Standard," RFC-1832, August 1995. 365 http://www.internic.net/rfc/rfc1832.txt 367 [RFC1833] R. Srinivasan, "Binding Protocols for ONC RPC 368 Version 2," RFC-1833, August 1995. 369 http://www.internic.net/rfc/rfc1833.txt 371 [RFC1094] Sun Microsystems, Inc., "Network Filesystem 372 Specification," RFC-1094, DDN Network 373 Information Center, SRI International, Menlo 374 Park, CA. NFS version 2 protocol 375 specification. 376 http://www.internic.net/rfc/rfc1094.txt 378 [RFC1813] Sun Microsystems, Inc., "NFS Version 3 Protocol 379 Specification," RFC-1813, DDN Network 380 Information Center, SRI International, Menlo 381 Park, CA. NFS version 3 protocol 382 specification. 383 http://www.internic.net/rfc/rfc1813.txt 385 [RFCmmmm] B. Callaghan, "WebNFS Client Specification," 386 RFC-mmmm, October 1996. 387 http://www.internic.net/rfc/rfcmmmm.txt 389 [Sandberg] Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, 390 B. Lyon, "Design and Implementation of the Sun 391 Network Filesystem," USENIX Conference 392 Proceedings, USENIX Association, Berkeley, CA, 393 Summer 1985. The basic paper describing the 394 SunOS implementation of the NFS version 2 395 protocol, and discusses the goals, protocol 396 specification and trade-offs. 398 [X/OpenNFS] X/Open Company, Ltd., X/Open CAE Specification: 399 Protocols for X/Open Internetworking: XNFS, 400 X/Open Company, Ltd., Apex Plaza, Forbury Road, 401 Reading Berkshire, RG1 1AX, United Kingdom, 402 1991. This is an indispensable reference for 403 NFS version 2 protocol and accompanying 404 protocols, including the Lock Manager and the 405 Portmapper. 407 [X/OpenPCNFS] X/Open Company, Ltd., X/Open CAE Specification: 408 Protocols for X/Open Internetworking: (PC)NFS, 409 Developer's Specification, X/Open Company, Ltd., 410 Apex Plaza, Forbury Road, Reading Berkshire, RG1 411 1AX, United Kingdom, 1991. This is an 412 indispensable reference for NFS version 2 413 protocol and accompanying protocols, including 414 the Lock Manager and the Portmapper. 416 10. Security Considerations 418 Since the WebNFS server features are based on NFS protocol 419 versions 2 and 3, the RPC security considerations described 420 in RFC 1094, RFC 1813, and Appendix A of RFC 1831 apply 421 here also. 423 Clients and servers may separately negotiate secure 424 connection schemes for authentication, data integrity, 425 and privacy. 427 Implementors must note carefully the implications of 428 export spanning pathnames as described in section 6.3. 430 11. Acknowledgements 432 This specification was extensively reviewed by the NFS 433 group at SunSoft and brainstormed by Michael Eisler. 435 12. Author's Address 437 Address comments related to this document to: 439 nfs@eng.sun.com 441 Brent Callaghan 442 Sun Microsystems, Inc. 443 2550 Garcia Avenue 444 Mailstop Mpk17-201 445 Mountain View, CA 94043-1100 447 Phone: 1-415-786-5067 448 Email: brent.callaghan@eng.sun.com 449 Fax: 1-415-786-5896