From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc2224.txt | 619 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 619 insertions(+) create mode 100644 doc/rfc/rfc2224.txt (limited to 'doc/rfc/rfc2224.txt') diff --git a/doc/rfc/rfc2224.txt b/doc/rfc/rfc2224.txt new file mode 100644 index 0000000..49a8c70 --- /dev/null +++ b/doc/rfc/rfc2224.txt @@ -0,0 +1,619 @@ + + + + + + +Network Working Group B. Callaghan +Request for Comments: 2224 Sun Microsystems, Inc. +Category: Informational October 1997 + + NFS URL Scheme + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +Abstract + + A new URL scheme, 'nfs' is defined. It is used to refer to files and + directories on NFS servers using the general URL syntax defined in + RFC 1738, "Uniform Resource Locators (URL)". + + This scheme uses the public filehandle and multi-component lookup + [RFC2054, RFC2055] to access server data with a minimum of protocol + overhead. + + The NFS protocol provides access to shared filesystems across + networks. It is designed to be machine, operating system, network + architecture, and transport protocol independent. The protocol + currently exists in two versions: version 2 [RFC1094] and version 3 + [RFC1813], both built on ONC RPC [RFC1831] at its associated eXternal + Data Representation (XDR) [RFC1832] and Binding Protocol [RFC1833]. + +Table of Contents + + 1. URL Syntax . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. URL Evaluation . . . . . . . . . . . . . . . . . . . . . 2 + 3. Server Connection . . . . . . . . . . . . . . . . . . . 2 + 4. NFS Version . . . . . . . . . . . . . . . . . . . . . . 2 + 5. Public Filehandle . . . . . . . . . . . . . . . . . . . 3 + 5.1 NFS Version 2 Public Filehandle . . . . . . . . . . . 3 + 5.2 NFS Version 3 Public Filehandle . . . . . . . . . . . 3 + 6. Multi-component Lookup . . . . . . . . . . . . . . . . . 3 + 6.1 Absolute vs Relative Pathname . . . . . . . . . . . . 4 + 6.2 Symbolic Links . . . . . . . . . . . . . . . . . . . . 5 + 7. Mount Protocol . . . . . . . . . . . . . . . . . . . . . 6 + 8. Bibliography . . . . . . . . . . . . . . . . . . . . . . 7 + 9. Security Considerations . . . . . . . . . . . . . . . . 8 + + + +Callaghan Informational [Page 1] + +RFC 2224 NFS URL Scheme October 1997 + + + 10. BNF for NFS URL Scheme . . . . . . . . . . . . . . . . . 9 + 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . 10 + 12. Author's Address . . . . . . . . . . . . . . . . . . . . 10 + 13. Full Copyright Statement . . . . . . . . . . . . . . . . 11 + +1. URL Syntax + + An NFS URL is based on the Common Internet Scheme Syntax described in + section 3.1 of RFC 1738. It has the general form: + + nfs://: + + The ":" part is optional. If omitted then port 2049 is + assumed. The is also optional. + + The is a hierarchical directory path of the form + ////.../. The must + consist only of characters within the US-ASCII character set. Within + a or component the character "/" is reserved and + must be encoded as described in Section 2.2 of RFC 1738. If is omitted or consists solely of "/", it must default to the + path ".". + +2. URL Evaluation + + A client must evaluate an NFS URL by a method known as WebNFS + [RFC2054, RFC2055]. This method provides easy passage through + firewalls and proxy servers, as well as using a minimum number of + messages. The WebNFS method is defined for NFS versions 2 and 3. It + assumes that the server registers on TCP or UDP port 2049 and + supports the public filehandle and multi-component lookup semantics + as described in the following sections. + +3. Server Connection + + The client must first attempt to create a TCP connection to + using the specified. If : is omitted, then port 2049 + will be used. If the server refuses the TCP connection, then the + client will use UDP. + +4. NFS Version + + The client must first attempt to use NFS version 3. If the server + returns an RPC PROG_MISMATCH error then the client must assume that + NFS version 3 is not supported, and retry the operation with an NFS + version 2 public filehandle. + + + + + +Callaghan Informational [Page 2] + +RFC 2224 NFS URL Scheme October 1997 + + +5. Public Filehandle + + NFS filehandles are normally created by the server and used to + identify uniquely a particular file or directory on the server. The + client does not normally create filehandles or have any knowledge of + the contents of a filehandle. + + The public filehandle is an an exception. It is an NFS filehandle + with a reserved value and special semantics that allow an initial + filehandle to be obtained. A WebNFS client uses the public + filehandle as an initial filehandle rather than using the MOUNT + protocol. Since NFS version 2 and version 3 have different + filehandle formats, the public filehandle is defined differently for + each. + + 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. + +5.1 NFS Version 2 Public Filehandle + + A version 2 filehandle is defined in RFC 1094 as an opaque value + occupying 32 octets. A version 2 public filehandle has a zero in + each octet, i.e. 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 NFS Version 3 Public Filehandle + + A version 3 filehandle is defined in RFC 1813 as a variable length + opaque value occupying up to 64 octets. The length of the filehandle + is indicated by an integer value contained in a 4 octet value which + describes the number of valid octets that follow. A version 3 public + filehandle has a length of zero. + + +-+-+-+-+ + | 0 | + +-+-+-+-+ + +6. Multi-component Lookup + + Normally the NFS LOOKUP request (version 2 or 3) takes a directory + filehandle along with the name of a directory member, and returns the + filehandle of the directory member. If a client needs to evaluate a + pathname that contains a sequence of components, then beginning with + + + +Callaghan Informational [Page 3] + +RFC 2224 NFS URL Scheme October 1997 + + + the directory filehandle of the first component it must issue a + series of LOOKUP requests one component at a time. For instance, + evaluation of the path "a/b/c" will generate separate LOOKUP + requests for each component of the pathname "a", "b", and "c". + + A LOOKUP request that uses the public filehandle can provide a + pathname containing multiple components. The server is expected to + evaluate the entire pathname and return a filehandle for the final + component. + + For example, rather than evaluate the path "a/b/c" as: + + LOOKUP FH=0x0 "a" ---> + <--- FH=0x1 + LOOKUP FH=0x1 "b" ---> + <--- FH=0x2 + LOOKUP FH=0x2 "c" ---> + <--- FH=0x3 + + 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. + + The of the NFS URL must be evaluated as a multi-component + lookup. This implies that the path components are delimited by + slashes and the characters that make up the path must be in the + printable US-ASCII character set. Characters not in the "unreserved" + set (see BNF description below) may be included in pathname + components but must be escaped. + + If the is empty or consists solely of "/", the client must + send a multi-component lookup for the pathname ".". + +6.1 Absolute vs. Relative Pathname + + A multi-component pathname that begins with a slash character is + considered "absolute" and will be evaluated relative to the server's + root. A pathname that does not begin with a slash is "relative" and + will be evaluated relative to the directory with which the public + filehandle is associated. + + + + + +Callaghan Informational [Page 4] + +RFC 2224 NFS URL Scheme October 1997 + + + Note that the initial "/" that introduces the of an NFS + URL must not be passed to the server for multi-component lookup since + the pathname is to be evaluated relative to the public filehandle + directory. For example, if the public filehandle is associated with + the server's directory "/a/b/c" then the URL: + + nfs://server/d/e/f + + will be evaluated with a multi-component lookup of the path + "d/e/f" relative to the server's directory "/a/b/c" while + the URL: + + nfs://server//a/b/c/d/e/f + + will locate the same file with an absolute multi-component lookup of + the path "/a/b/c/d/e/f" relative to the server's filesystem root. + Notice that a double slash is required at the beginning of the path. + + Not all WebNFS servers can support arbitrary use of absolute paths. + Clearly, the server must not 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. + +6.2 Symbolic Links + + The NFS protocol supports symbolic links, which are the filesystem + equivalent of a relative URL. If a WebNFS client retrieves a + filehandle for a symbolic link (as indicated by the file type + attribute) then it should send a READLINK request to the server to + retrieve the path comprising the symbolic link. + + This path should then be combined with the URL which referenced the + symbolic link according to the rules described in RFC 1808. If the + relative URL in the symbolic link text is to be resolved successfully + then it must contain only ASCII characters and conform to the syntax + described in RFC 1808. Note that this allows a symbolic link to + contain an entire URL and it may specify a scheme that is not + necessarily an NFS URL. + + A symbolic link path that begins with a slash will be evaluated as an + absolute path relative to the directory associated with the public + filehandle which may not be the same as the server's system root + directory. If symbolic links with absolute paths are to be evaluated + correctly on both client and server then the public filehandle must + be associated with the system root directory. + + + + +Callaghan Informational [Page 5] + +RFC 2224 NFS URL Scheme October 1997 + + + For example, if the symbolic link is named by the URL + + nfs://server/a/b + + then the following examples show how a new URL can be + formed from the symbolic link text: + + c = nfs://server/a/c + + c/d = nfs://server/a/c/d + + ../c = nfs://server/c + + /c/d = nfs://server/c/d + + nfs://server2/a/b = nfs://server2/a/b + +7. Mount Protocol + + The NFS URL may have limited use for naming files on servers that do + not support the public filehandle and multi-component lookup. + + If the server returns an NFS3ERR_STALE, NFS3ERR_INVAL, or + NFS3ERR_BADHANDLE error in response to the client's use of a public + filehandle, then the client should attempt to resolve the + to a filehandle using the MOUNT protocol. + + Version 1 of the MOUNT protocol is described in Appendix A of RFC + 1094 and version 3 in Appendix I of RFC 1813. Version 2 of the MOUNT + protocol is identical to version 1 except for the addition of a + procedure MOUNTPROC_PATHCONF which returns POSIX pathconf information + from the server. + + Note that the pathname sent to the server in the MOUNTPROC_MNT + request is assumed to be a server native path, rather than a slash- + separated path described by RFC 1738. Hence, the MOUNT protocol can + reasonably be expected to map a to a filehandle only on + servers that support slash-separated ASCII native paths. In general, + servers that do not support WebNFS access or slash-separated ASCII + native paths should not advertise NFS URLs. + + At this point the client must already have some indication as to + which version of the NFS protocol is supported on the server. Since + the filehandle format differs between NFS versions 2 and 3, the + client must select the appropriate version of the MOUNT protocol. + MOUNT versions 1 and 2 return only NFS version 2 filehandles, whereas + MOUNT version 3 returns NFS version 3 filehandles. + + + + +Callaghan Informational [Page 6] + +RFC 2224 NFS URL Scheme October 1997 + + + Unlike the NFS service, the MOUNT service is not registered on a + well-known port. The client must use the PORTMAP service to locate + the server's MOUNT port before it can transmit a MOUNTPROC_MNT + request to retrieve the filehandle corresponding to the requested + path. + + Client Server + ------ ------ + + -------------- MOUNT port ? --------------> Portmapper + <-------------- Port=984 ------------------ + + ------- Filehandle for /export/foo ? ----> Mountd @ port 984 + <--------- Filehandle=0xf82455ce0.. ------ + + NFS servers commonly use a client's successful MOUNTPROC_MNT request + request as an indication that the client has "mounted" the filesystem + and may maintain this information in a file that lists the + filesystems that clients currently have mounted. This information is + removed from the file when the client transmits an MOUNTPROC_UMNT + request. Upon receiving a successful reply to a MOUNTPROC_MNT + request, a WebNFS client should send a MOUNTPROC_UMNT request to + prevent an accumulation of "mounted" records on the server. + +8.0 Bibliography + + [RFC1738] Berners-Lee, T., Masinter, L. and M. McCahill, + "Uniform Resource Locators (URL)," RFC 1738, + December 1994. + + [RFC1808] Fielding, R., "Relative Uniform Resource Locators," + RFC 1808, June 1995. + + [RFC1831] Srinivasan, R., "RPC: Remote Procedure Call + Protocol Specification Version 2," RFC 1831, + August 1995. + + [RFC1832] Srinivasan, R., "XDR: External Data Representation + Standard," RFC 1832, August 1995. + + [RFC1833] Srinivasan, R., "Binding Protocols for ONC RPC + Version 2," RFC 1833, August 1995. + + [RFC1094] Sun Microsystems, Inc., "Network Filesystem + Specification," RFC 1094, March 1989. + + + + + + +Callaghan Informational [Page 7] + +RFC 2224 NFS URL Scheme October 1997 + + + [RFC1813] Callaghan, B., Pawlowski, B. and P. Staubach, + "NFS Version 3 Protocol Specification," RFC 1813, + June 1995. + + [RFC2054] Callaghan, B., "WebNFS Client Specification," + RFC 2054, October 1996. + + [RFC2055] Callaghan, B., "WebNFS Server Specification," + RFC 2055, October 1996. + + [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 + the NFS 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 protocol and + accompanying protocols, including the Lock Manager + and the Portmapper. + +9. Security Considerations + + Since the WebNFS server features are based on NFS protocol versions 2 + and 3, the RPC based security considerations described in RFC 1094, + RFC 1831, and RFC 1832 apply here also. + + Server implementors should be careful when implementing multi- + component lookup that the client cannot obtain unauthorized access to + files or directories. For example: a path that includes multiple + occurrences of "../" may locate a filesystem outside of the exported + filesystem associated with the public filehandle. + + + + +Callaghan Informational [Page 8] + +RFC 2224 NFS URL Scheme October 1997 + + + Clients and servers may separately negotiate secure connection + schemes for authentication, data integrity, and privacy. + +10. BNF for NFS URL Scheme + + The syntax of the NFS URL is a subset of the Generic URL syntax + described in RFC 1738. An NFS URL does not include user or password + components, nor does it recognize "?" query or "#" fragment + components. + nfsURL = "nfs" ":" relativeURL + relativeURL = net_path | abs_path | rel_path + net_path = "//" hostport [ abs_path ] + abs_path = "/" rel_path + rel_path = [ path_segments ] + + hostport = host [ ":" port ] + host = hostname | hostnumber + hostname = *( domainlabel "." ) toplabel + domainlabel = alphanum | alphanum *( alphanum | "-" ) alphanum + toplabel = alpha | alpha *( alphanum | "-" ) alphanum + hostnumber = 1*digit "." 1*digit "." 1*digit "." 1*digit + port = *digit + + url-path = [ "/" ] path_segments + path_segments = segment *( "/" segment ) + segment = *pchar + pchar = unreserved | escaped | ":" | "@" | "&" | "=" | "+" + + reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" + unreserved = alpha | digit | mark + mark = "$" | "-" | "_" | "." | "!" | "~" | + "*" | "'" | "(" | ")" | "," + + escaped = "%" hex hex + hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | + "a" | "b" | "c" | "d" | "e" | "f" + + alphanum = alpha | digit + alpha = lowalpha | upalpha + + lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | + "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | + "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" + upalpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | + "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | + "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" + digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | + "8" | "9" + + + +Callaghan Informational [Page 9] + +RFC 2224 NFS URL Scheme October 1997 + + +11. Acknowledgements + + This specification was extensively reviewed by the NFS group at + SunSoft and brainstormed by Michael Eisler. + +12. Author's Address + + Address comments related to this RFC to: + + brent@eng.sun.com + + + Brent Callaghan + Sun Microsystems, Inc. + Mailstop Mpk17-201, + 901 San Antonio Road, + Palo Alto, California 94303 + + Phone: 1-415-786-5067 + EMail: brent.callaghan@eng.sun.com + Fax: 1-415-786-5896 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Callaghan Informational [Page 10] + +RFC 2224 NFS URL Scheme October 1997 + + +13. Full Copyright Statement + + Copyright (C) The Internet Society (1997). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implmentation may be prepared, copied, published + andand distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." + + + + + + + + + + + + + + + + + + + + + + + + +Callaghan Informational [Page 11] + -- cgit v1.2.3