idnits 2.17.1 draft-callaghan-url-nfs-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-23) 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 9 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 10 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** 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.) ** The abstract seems to contain references ([RFC1831], [RFC1094], [RFC1832], [RFC1833], [RFC1813]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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 (April 1, 1997) is 9884 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC1094' on line 361 looks like a reference -- Missing reference section? 'RFC1813' on line 367 looks like a reference -- Missing reference section? 'RFC1831' on line 348 looks like a reference -- Missing reference section? 'RFC1832' on line 353 looks like a reference -- Missing reference section? 'RFC1833' on line 357 looks like a reference -- Missing reference section? 'RFC1738' on line 338 looks like a reference -- Missing reference section? 'RFC1808' on line 343 looks like a reference -- Missing reference section? 'Sandberg' on line 373 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 3 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft 2 draft-callaghan-url-nfs-00.txt 3 October 1, 1996 4 Expires April 1, 1997 6 NFS URL Scheme 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its 12 areas, and its working groups. Note that other groups may also 13 distribute working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or obsoleted by other 17 documents at any time. It is inappropriate to use Internet- 18 Drafts as reference material or to cite them other than as 19 ``work in progress.'' 21 To learn the current status of any Internet-Draft, please check 22 the ``1id-abstracts.txt'' listing contained in the Internet- 23 Drafts Shadow Directories on ftp.is.co.za (Africa), 24 nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), 25 ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). 27 Abstract 29 A new URL scheme, "nfs:" is defined. It is used to refer 30 to files and directories on NFS servers. The scheme uses 31 the public filehandle and multi-component lookup to access 32 server data with a minimum of protocol overhead. 34 The NFS protocol provides access to shared filesystems 35 across networks. It is designed to be machine, operating 36 system, network architecture, and transport protocol independent. 37 The protocol currently exists in two versions: version 2 [RFC1094] 38 and version 3 [RFC1813], both built on ONC RPC [RFC1831] at its 39 associated eXternal Data Representation (XDR) [RFC1832] and 40 Binding Protocol [RFC1833]. 42 Table of Contents 44 1. URL Syntax . . . . . . . . . . . . . . . . . . . . . . . . 2 45 2. URL Evaluation . . . . . . . . . . . . . . . . . . . . . . 2 46 3. Server Connection . . . . . . . . . . . . . . . . . . . . 2 47 4. NFS Version . . . . . . . . . . . . . . . . . . . . . . . 3 48 5. Public Filehandle . . . . . . . . . . . . . . . . . . . . 3 49 5.1 NFS Version 2 Public Filehandle . . . . . . . . . . . . 3 50 5.2 NFS Version 3 Public Filehandle . . . . . . . . . . . . 3 51 6. Multi-component Lookup . . . . . . . . . . . . . . . . . . 4 52 6.1 Absolute vs Relative Pathname . . . . . . . . . . . . . 5 53 6.2 Symbolic Links . . . . . . . . . . . . . . . . . . . . . 5 54 7. Mount Protocol . . . . . . . . . . . . . . . . . . . . . . 6 55 8. Bibliography . . . . . . . . . . . . . . . . . . . . . . . 8 56 9. Security Considerations . . . . . . . . . . . . . . . . . 9 57 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 9 58 11. Author's Address . . . . . . . . . . . . . . . . . . . . . 9 60 1. URL Syntax 62 An NFS URL is based on the Common Internet Scheme Syntax described 63 in section 3.1 of RFC 1738. It has the general form: 65 nfs://:/ 67 The ":" part is optional. If omitted then port 2049 is 68 assumed. The is also optional. If it is omitted, then 69 the "/" between : and may also be omitted. 71 The is a hierarchical directory path of the form 72 ///.../. The 73 must consist only of characters within the US-ASCII character 74 set. Within a or component the character "/" 75 is reserved and must be encoded as described in Section 2.2 of RFC 76 1738. If is omitted, it must default to the path ".". 78 2. URL Evaluation 80 A client must evaluate an NFS URL by a method known as WebNFS. 81 This method provides easy passage through firewalls and proxy 82 servers, as well as using a minimum number of messages. The 83 WebNFS method is defined for NFS versions 2 and 3. It assumes that 84 the server registers on TCP or UDP port 2049 and supports the 85 public filehandle and multi-component lookup semantics as 86 described in the following sections. 88 3. Server Connection 90 The client must first attempt to create a TCP connection to 91 using the specified. If : is omitted, then port 2049 92 will be used. If the server refuses the TCP connection, then the 93 client will use UDP. 95 4. NFS Version 97 The client must first attempt to use NFS version 3. If the server 98 returns an RPC PROG_MISMATCH error then the client must assume 99 that NFS version 3 is not supported, and retry the operation with 100 an NFS version 2 public filehandle. 102 5. Public Filehandle 104 NFS filehandles are normally created by the server and used to 105 identify uniquely a particular file or directory on the server. 106 The client does not normally create filehandles or have any 107 knowledge of the contents of a filehandle. 109 The public filehandle is an an exception. It is an NFS filehandle 110 with a reserved value and special semantics that allow an initial 111 filehandle to be obtained. A WebNFS client uses the public 112 filehandle as an initial filehandle rather than using the MOUNT 113 protocol. Since NFS version 2 and version 3 have different 114 filehandle formats, the public filehandle is defined differently 115 for each. 117 The public filehandle is a zero filehandle. For NFS version 2 118 this is a filehandle with 32 zero octets. A version 3 public 119 filehandle has zero length. 121 5.1 NFS Version 2 Public Filehandle 123 A version 2 filehandle is defined in RFC 1094 as an opaque value 124 occupying 32 octets. A version 2 public filehandle has a zero 125 in each octet, i.e. all zeros. 127 1 32 128 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 129 |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| 130 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 132 5.2 NFS Version 3 Public Filehandle 134 A version 3 filehandle is defined in RFC 1813 as a variable length 135 opaque value occupying up to 64 octets. The length of the filehandle 136 is indicated by an integer value contained in a 4 octet value 137 which describes the number of valid octets that follow. A version 138 3 public filehandle has a length of zero. 140 +-+-+-+-+ 141 | 0 | 142 +-+-+-+-+ 144 6. Multi-component Lookup 146 Normally the NFS LOOKUP request (version 2 or 3) takes a directory 147 filehandle along with the name of a directory member, and returns 148 the filehandle of the directory member. If a client needs to 149 evaluate a pathname that contains a sequence of components, then 150 beginning with the directory filehandle of the first component it 151 must issue a series of LOOKUP requests one component at a time. 152 For instance, evaluation of the path "a/b/c" will generate 153 separate LOOKUP requests for each component of the pathname "a", 154 "b", and "c". 156 A LOOKUP request that uses the public filehandle can provide a 157 pathname containing multiple components. The server is expected 158 to evaluate the entire pathname and return a filehandle for the 159 final component. 161 For example, rather than evaluate the path "a/b/c" as: 163 LOOKUP FH=0x0 "a" ---> 164 <--- FH=0x1 165 LOOKUP FH=0x1 "b" ---> 166 <--- FH=0x2 167 LOOKUP FH=0x2 "c" ---> 168 <--- FH=0x3 170 Relative to the public filehandle these three LOOKUP 171 requests can be replaced by a single multi-component 172 lookup: 174 LOOKUP FH=0x0 "a/b/c" ---> 175 <--- FH=0x3 177 Multi-component lookup is supported only for LOOKUP requests 178 relative to the public filehandle. 180 The of the NFS URL must be evaluated as a 181 multi-component lookup. This implies that the path components are 182 delimited by slashes and the characters that make up the path must 183 be in the printable US-ASCII character set. 185 If the is empty, the client must send a multi-component 186 lookup for the pathname ".". 188 6.1 Absolute vs. Relative Pathname 190 A pathname that begins with a slash character is considered 191 "absolute" and will be evaluated relative to the server's root. 192 A pathname that does not begin with a slash is "relative" and will 193 be evaluated relative to the directory with which the public 194 filehandle is associated. 196 Note that the "/" in an NFS URL that delimits the : 197 from the is not considered part of the pathname. For 198 example, if the public filehandle is associated with the server's 199 directory "/a/b/c" then the URL: 201 nfs://server/d/e/f 203 will be evaluated with a relative multi-component lookup of the 204 path "d/e/f" relative to the server's directory "/a/b/c" while 205 the URL: 207 nfs://server//a/b/c/d/e/f 209 will locate the same file with an absolute multi-component lookup 210 of the path "/a/b/c/d/e/f" relative to the server's filesystem 211 root. Notice that a double slash is required at the beginning of 212 the path; the first slash is the URL delimiter between the 213 : and the and the second slash is the first 214 character of . 216 Not all WebNFS servers can support arbitrary use of absolute 217 paths. Clearly, the server must not return a filehandle if the 218 path identifies a file or directory that is not exported by the 219 server. In addition, some servers will not return a filehandle if 220 the path names a file or directory in an exported filesystem 221 different from the one that is associated with the public 222 filehandle. 224 6.2 Symbolic Links 226 The NFS protocol supports symbolic links, which are the 227 filesystem equivalent of a relative URL. If a WebNFS 228 client retrieves a filehandle for a symbolic link (as 229 indicated by the file type attribute) then it should 230 send a READLINK request to the server to retrieve the 231 path comprising the symbolic link. 233 This path should then be combined with the URL which referenced 234 the symbolic link according to the rules described in RFC 1808. 235 If the relative URL in the symbolic link text is to be resolved 236 successfully then it must contain only ASCII characters and 237 conform to the syntax described in RFC 1808. Note that this 238 allows a symbolic link to contain an entire URL and it may specify 239 a scheme that is not necessarily an NFS URL. 241 An exception to RFC 1808 rules applies in the case of an absolute 242 symbolic link, where the path begins with a "/". RFC 1808 243 describes a method for resolving relative URLs with respect 244 to the base URL. Given a base URL of "nfs://s/a/b/c" that 245 references a symbolic link with contents "/a/b/c/d", the method 246 would yield a URL "nfs://s/a/b/c/d" which would be correct only 247 if the public filehandle were co-located with the server's 248 filesystem root. 250 If the symbolic link begins with a slash, then after resolving 251 a relative URL derived from the symbolic link contents according 252 to the method in RFC 1808, the client must insert an additional 253 slash in front of the path so that the server will evaluate the 254 path relative to the server's root, rather than the public 255 filehandle directory. This variation from the normal method 256 of resolving a relative URL applies only to handling of symbolic 257 links. The additional slash must not be inserted if the relative 258 URL was embedded in a document or other encapsulating entity. 260 For example, if the symbolic link is named by the URL 262 nfs://server/a/b 264 then the the following examples show how a new URL can be 265 formed from the symbolic link text: 267 c = nfs://server/a/c 269 c/d = nfs://server/a/c/d 271 ../c = nfs://server/c 273 /c/d = nfs://server//c/d 275 nfs://server2/a/b = nfs://server2/a/b 277 7. Mount Protocol 279 The NFS URL may have limited use for naming files on 280 servers that do not support the public filehandle and 281 multi-component lookup. 283 If the server returns an NFS3ERR_STALE, NFS3ERR_INVAL, or 284 NFS3ERR_BADHANDLE error in response to the client's use of 285 a public filehandle, then the client should attempt to resolve 286 the to a filehandle using the MOUNT protocol. 288 Version 1 of the MOUNT protocol is described in Appendix A of 289 RFC 1094 and version 3 in Appendix I of RFC 1813. Version 2 290 of the MOUNT protocol is identical to version 1 except for 291 the addition of a procedure MOUNTPROC_PATHCONF which returns 292 POSIX pathconf information from the server. 294 Note that the pathname sent to the server in the MOUNTPROC_MNT 295 request is assumed to be a server native path, rather than 296 a slash-separated path described by RFC 1738. Hence, the 297 MOUNT protocol can reasonably be expected to map a 298 to a filehandle only on servers that support slash-separated 299 ASCII native paths. In general, servers that do not support 300 WebNFS access or slash-separated ASCII native paths should not 301 advertise NFS URLs. 303 At this point the client must already have some indication 304 as to which version of the NFS protocol is supported on the 305 server. Since the filehandle format differs between NFS 306 versions 2 and 3, the client must select the appropriate 307 version of the MOUNT protocol. MOUNT versions 1 and 2 return 308 only NFS version 2 filehandles, whereas MOUNT version 3 returns 309 NFS version 3 filehandles. 311 Unlike the NFS service, the MOUNT service is not registered on a 312 well-known port. The client must use the PORTMAP service to 313 locate the server's MOUNT port before it can transmit a 314 MOUNTPROC_MNT request to retrieve the filehandle corresponding to 315 the requested path. 317 Client Server 318 ------ ------ 320 -------------- MOUNT port ? --------------> Portmapper 321 <-------------- Port=984 ------------------ 323 ------- Filehandle for /export/foo ? ----> Mountd @ port 984 324 <--------- Filehandle=0xf82455ce0.. ------ 326 NFS servers commonly use a client's successful MOUNTPROC_MNT 327 request request as an indication that the client has "mounted" 328 the filesystem and may maintain this information in a file 329 that lists the filesystems that clients currently have mounted. 330 This information is removed from the file when the client 331 transmits an MOUNTPROC_UMNT request. Upon receiving a 332 successful reply to a MOUNTPROC_MNT request, a WebNFS client 333 should send a MOUNTPROC_UMNT request to prevent an accumulation 334 of "mounted" records on the server. 336 8.0 Bibliography 338 [RFC1738] T. Berners-Lee, L. Masinter, M. McCahill, 339 "Uniform Resource Locators (URL)," RFC-1738, 340 December 1994. 341 http://www.internic.net/rfc/rfc1738.txt 343 [RFC1808] R. Fielding, 344 "Relative Uniform Resource Locators," RFC-1808, 345 June 1995 346 http://www.internic.net/rfc/rfc1808.txt 348 [RFC1831] R. Srinivasan, "RPC: Remote Procedure Call 349 Protocol Specification Version 2," RFC-1831, 350 August 1995. 351 http://www.internic.net/rfc/rfc1831.txt 353 [RFC1832] R. Srinivasan, "XDR: External Data Representation 354 Standard," RFC-1832, August 1995. 355 http://www.internic.net/rfc/rfc1832.txt 357 [RFC1833] R. Srinivasan, "Binding Protocols for ONC RPC 358 Version 2," RFC-1833, August 1995. 359 http://www.internic.net/rfc/rfc1833.txt 361 [RFC1094] Sun Microsystems, Inc., "Network Filesystem 362 Specification," RFC-1094, DDN Network 363 Information Center, SRI International, Menlo 364 Park, CA. NFS version 2 protocol specification. 365 http://www.internic.net/rfc/rfc1094.txt 367 [RFC1813] Sun Microsystems, Inc., "NFS Version 3 Protocol 368 Specification," RFC-1813, DDN Network 369 Information Center, SRI International, Menlo 370 Park, CA. NFS version 3 protocol specification. 371 http://www.internic.net/rfc/rfc1813.txt 373 [Sandberg] Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, 374 B. Lyon, "Design and Implementation of the Sun 375 Network Filesystem," USENIX Conference 376 Proceedings, USENIX Association, Berkeley, CA, 377 Summer 1985. The basic paper describing the 378 SunOS implementation of the NFS version 2 379 protocol, and discusses the goals, protocol 380 specification and trade-offs. 382 [X/OpenNFS] X/Open Company, Ltd., X/Open CAE Specification: 383 Protocols for X/Open Internetworking: XNFS, 384 X/Open Company, Ltd., Apex Plaza, Forbury Road, 385 Reading Berkshire, RG1 1AX, United Kingdom, 386 1991. This is an indispensable reference for 387 NFS version 2 protocol and accompanying 388 protocols, including the Lock Manager and the 389 Portmapper. 391 [X/OpenPCNFS] X/Open Company, Ltd., X/Open CAE Specification: 392 Protocols for X/Open Internetworking: (PC)NFS, 393 Developer's Specification, X/Open Company, Ltd., 394 Apex Plaza, Forbury Road, Reading Berkshire, RG1 395 1AX, United Kingdom, 1991. This is an 396 indispensable reference for NFS version 2 397 protocol and accompanying protocols, including 398 the Lock Manager and the Portmapper. 400 9. Security Considerations 402 Since the WebNFS server features are based on NFS protocol 403 versions 2 and 3, the RPC based security considerations 404 described in RFC 1094, RFC 1831, and RFC 1832 apply here also. 406 Clients and servers may separately negotiate secure 407 connection schemes for authentication, data integrity, 408 and privacy. 410 10. Acknowledgements 412 This specification was extensively reviewed by the NFS 413 group at SunSoft and brainstormed by Michael Eisler. 415 11. Author's Address 417 Address comments related to this document to: 419 nfs@eng.sun.com 421 Brent Callaghan 422 Sun Microsystems, Inc. 423 2550 Garcia Avenue 424 Mailstop Mpk17-201 425 Mountain View, CA 94043-1100 427 Phone: 1-415-786-5067 428 Email: brent.callaghan@eng.sun.com 429 Fax: 1-415-786-5896