idnits 2.17.1 draft-ietf-nfsv4-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 4 longer pages, the longest (page 26) being 62 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 157 pages 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.) ** The abstract seems to contain references ([RFC1094], [RFC1813]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 2965 has weird spacing: '...ameorfh file...' == Line 2967 has weird spacing: '...ckowner owne...' == Line 5008 has weird spacing: '...S4resok reso...' == Line 5028 has weird spacing: '...T4resok reso...' == Line 5075 has weird spacing: '...ck_type type;...' == (10 more instances...) -- 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 (June 1999) is 9075 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: 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 5708 looks like a reference -- Missing reference section? 'RFC1813' on line 5720 looks like a reference -- Missing reference section? 'RFC1831' on line 5726 looks like a reference -- Missing reference section? 'RFC1832' on line 5732 looks like a reference -- Missing reference section? 'RFC2203' on line 5768 looks like a reference -- Missing reference section? 'RFC1833' on line 5738 looks like a reference -- Missing reference section? 'RFC2078' on line 5756 looks like a reference -- Missing reference section? 'RFC1964' on line 240 looks like a reference -- Missing reference section? 'RFC2054' on line 5744 looks like a reference -- Missing reference section? 'RFC2055' on line 5750 looks like a reference -- Missing reference section? 'XNFS' on line 5816 looks like a reference -- Missing reference section? '4' on line 1345 looks like a reference -- Missing reference section? 'RFC 2078' on line 4015 looks like a reference -- Missing reference section? 'RFC1345' on line 5714 looks like a reference -- Missing reference section? 'RFC2279' on line 5774 looks like a reference -- Missing reference section? 'RFC2152' on line 5762 looks like a reference -- Missing reference section? 'Unicode1' on line 5803 looks like a reference -- Missing reference section? 'Unicode2' on line 5810 looks like a reference -- Missing reference section? 'Gray' on line 5663 looks like a reference -- Missing reference section? 'Juszczak' on line 5668 looks like a reference -- Missing reference section? 'Kazar' on line 5677 looks like a reference -- Missing reference section? 'Macklem' on line 5684 looks like a reference -- Missing reference section? 'Mogul' on line 5801 looks like a reference -- Missing reference section? 'Nowicki' on line 5697 looks like a reference -- Missing reference section? 'Pawlowski' on line 5702 looks like a reference -- Missing reference section? 'Sandberg' on line 5780 looks like a reference -- Missing reference section? 'SPNEGO' on line 5788 looks like a reference -- Missing reference section? 'Srinivasan' on line 5794 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 31 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 NFS Version 4 Working Group S. Shepler 2 INTERNET-DRAFT B. Callaghan 3 Document: draft-ietf-nfsv4-00.txt M. Eisler 4 D. Robinson 5 R. Thurlow 6 Sun Microsystems 7 June 1999 9 NFS version 4 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet- Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 Abstract 34 NFS version 4 is a distributed file system protocol which owes 35 heritage to NFS versions 2 [RFC1094] and 3 [RFC1813]. Unlike earlier 36 versions, NFS version 4 supports traditional file access while 37 integrating support for file locking and the mount protocol. In 38 addition, support for strong security (and its negotiation), compound 39 operations, and internationlization have been added. Of course, 40 attention has been applied to making NFS version 4 operate well in an 41 Internet environment. 43 Copyright 45 Copyright (C) The Internet Society (1999). All Rights Reserved. 47 Key Words 49 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 50 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 51 document are to be interpreted as described in RFC 2119. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 56 2. RPC and Security Flavor . . . . . . . . . . . . . . . . . . 7 57 2.1. Ports and Transports . . . . . . . . . . . . . . . . . . . 7 58 2.2. Security Flavors . . . . . . . . . . . . . . . . . . . . . 7 59 2.2.1. Security mechanisms for NFS version 4 . . . . . . . . . 7 60 2.2.1.1. Kerberos V5 as security triple . . . . . . . . . . . . 7 61 2.2.1.2. . . . . . . . . . . . . . . 8 62 2.3. Security Negotiation . . . . . . . . . . . . . . . . . . . 8 63 2.3.1. Security Error . . . . . . . . . . . . . . . . . . . . . 8 64 2.3.2. SECINFO . . . . . . . . . . . . . . . . . . . . . . . . 9 65 3. File handles . . . . . . . . . . . . . . . . . . . . . . . 10 66 3.1. Obtaining the First File Handle . . . . . . . . . . . . 10 67 3.1.1. Root File Handle . . . . . . . . . . . . . . . . . . . 10 68 3.1.2. Public File Handle . . . . . . . . . . . . . . . . . . 11 69 3.2. File Handle Types . . . . . . . . . . . . . . . . . . . 11 70 3.2.1. General Properties of a File Handle . . . . . . . . . 12 71 3.2.2. Persistent File Handle . . . . . . . . . . . . . . . . 12 72 3.2.3. Volatile File Handle . . . . . . . . . . . . . . . . . 13 73 3.2.4. One Method of Constructing a Volatile File Handle . . 14 74 3.3. Client Recovery from File Handle Expiration . . . . . . 15 75 4. Basic Data Types . . . . . . . . . . . . . . . . . . . . . 16 76 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 18 77 5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 19 78 5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 19 79 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 20 80 5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 20 81 5.5. Recommended Attributes - Definitions . . . . . . . . . . 22 82 6. NFS Server Namespace . . . . . . . . . . . . . . . . . . . 28 83 6.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 28 84 6.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 28 85 6.3. Server Pseudo File-System . . . . . . . . . . . . . . . 29 86 6.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 29 87 6.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 29 88 6.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 29 89 6.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 30 90 6.8. Summary . . . . . . . . . . . . . . . . . . . . . . . . 30 91 7. File Locking . . . . . . . . . . . . . . . . . . . . . . . 31 92 7.1. Definitions . . . . . . . . . . . . . . . . . . . . . . 31 93 7.2. Locking . . . . . . . . . . . . . . . . . . . . . . . . 32 94 7.2.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 32 95 7.2.2. nfs_lockowner and stateid definition . . . . . . . . . 34 96 7.2.3. Use of the stateid . . . . . . . . . . . . . . . . . . 34 97 7.2.4. Sequencing of lock requests . . . . . . . . . . . . . 35 98 7.3. Blocking locks . . . . . . . . . . . . . . . . . . . . . 35 99 7.4. Lease renewal . . . . . . . . . . . . . . . . . . . . . 36 100 7.5. Crash recovery . . . . . . . . . . . . . . . . . . . . . 36 101 7.6. Server revocation of locks . . . . . . . . . . . . . . . 37 102 7.7. Share Reservations . . . . . . . . . . . . . . . . . . . 38 103 7.8. OPEN/CLOSE procedures . . . . . . . . . . . . . . . . . 38 104 8. Defined Error Numbers . . . . . . . . . . . . . . . . . . 40 105 9. NFS Version 4 Requests . . . . . . . . . . . . . . . . . . 45 106 9.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 45 107 9.2. Evaluation of a Compound Request . . . . . . . . . . . . 45 108 10. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 47 109 10.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 47 110 10.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 48 111 10.3. Procedure 2: ACCESS - Check Access Permission . . . . . 50 112 10.4. Procedure 3: CLOSE - Close File . . . . . . . . . . . . 53 113 10.5. Procedure 4: COMMIT - Commit Cached Data . . . . . . . 55 114 10.6. Procedure 5: CREATE - Create a Non-Regular File Object 58 115 10.7. Procedure 6: GETATTR - Get Attributes . . . . . . . . . 62 116 10.8. Procedure 7: GETFH - Get Current Filehandle . . . . . . 64 117 10.9. Procedure 8: LINK - Create Link to a File . . . . . . . 66 118 10.10. Procedure 9: LOCK - Create Lock . . . . . . . . . . . 68 119 10.11. Procedure 10: LOCKT - Test For Lock . . . . . . . . . 70 120 10.12. Procedure 11: LOCKU - Unlock File . . . . . . . . . . 72 121 10.13. Procedure 12: LOOKUP - Lookup Filename . . . . . . . . 74 122 10.14. Procedure 13: LOOKUPP - Lookup Parent Directory . . . 77 123 10.15. Procedure 14: NVERIFY - Verify Difference in Attributes 79 124 10.16. Procedure 15: OPEN - Open a Regular File . . . . . . . 81 125 10.17. Procedure 16: OPENATTR - Open Named Attribute Directory 86 126 10.18. Procedure 17: PUTFH - Set Current Filehandle . . . . . 88 127 10.19. Procedure 18: PUTPUBFH - Set Public Filehandle . . . . 89 128 10.20. Procedure 19: PUTROOTFH - Set Root Filehandle . . . . 90 129 10.21. Procedure 20: READ - Read from File . . . . . . . . . 91 130 10.22. Procedure 21: READDIR - Read Directory . . . . . . . . 94 131 10.23. Procedure 22: READLINK - Read Symbolic Link . . . . . 98 132 10.24. Procedure 23: REMOVE - Remove Filesystem Object . . . 100 133 10.25. Procedure 24: RENAME - Rename Directory Entry . . . . 102 134 10.26. Procedure 25: RENEW - Renew a Lease . . . . . . . . . 105 135 10.27. Procedure 25: RESTOREFH - Restore Saved Filehandle . . 106 136 10.28. Procedure 27: SAVEFH - Save Current Filehandle . . . . 108 137 10.29. Procedure 28: SECINFO - Obtain Available Security . . 109 138 10.30. Procedure 29: SETATTR - Set Attributes . . . . . . . . 111 139 10.31. Procedure 30: SETCLIENTID - Negotiated Clientid . . . 114 140 10.32. Procedure 31: VERIFY - Verify Same Attributes . . . . 116 141 10.33. Procedure 32: WRITE - Write to File . . . . . . . . . 118 142 11. Locking notes . . . . . . . . . . . . . . . . . . . . . . 123 143 11.1. Short and long leases . . . . . . . . . . . . . . . . . 123 144 11.2. Clocks and leases . . . . . . . . . . . . . . . . . . . 123 145 11.3. Locks and lease times . . . . . . . . . . . . . . . . . 123 146 11.4. Locking of directories and other meta-files . . . . . . 124 147 11.5. Proxy servers and leases . . . . . . . . . . . . . . . 124 148 11.6. Locking and the new latency . . . . . . . . . . . . . . 124 149 12. Internationalization . . . . . . . . . . . . . . . . . . 125 150 12.1. Universal Versus Local Character Sets . . . . . . . . . 125 151 12.2. Overview of Universal Character Set Standards . . . . . 126 152 12.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 127 153 12.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 128 154 13. Security Considerations . . . . . . . . . . . . . . . . . 129 155 14. NFS Version 4 RPC definition file . . . . . . . . . . . . 130 156 15. Bibliography . . . . . . . . . . . . . . . . . . . . . . 151 157 16. Authors and Contributors . . . . . . . . . . . . . . . . 155 158 16.1. Contributors . . . . . . . . . . . . . . . . . . . . . 155 159 16.2. Editor's Address . . . . . . . . . . . . . . . . . . . 155 160 16.3. Authors' Addresses . . . . . . . . . . . . . . . . . . 155 161 17. Full Copyright Statement . . . . . . . . . . . . . . . . 157 163 1. Introduction 165 NFS version 4 is a further revision of the NFS protocol defined 166 already by versions 2 [RFC1094] and 3 [RFC1813]. It retains the 167 essential characteristics of previous versions: stateless design for 168 easy recovery, independent of transport protocols, operating systems 169 and filesystems, simplicity, and good performance. The NFS version 4 170 revision has the following goals: 172 o Improved access and good performance on the Internet. 174 The protocol is designed to transit firewalls easily, perform 175 well where latency is high and bandwidth is low, and scale to 176 very large numbers of clients per server. 178 o Strong security with negotiation built into the protocol. 180 The protocol builds on the work of the ONCRPC working group in 181 supporting the RPCSEC_GSS protocol. Additionally NFS version 4 182 provides a mechanism to allow clients and servers to negotiate 183 security and require clients and servers to support a minimal 184 set of security schemes. 186 o Good cross-platform interoperability. 188 The protocol features a filesystem model that provides a useful, 189 common set of features that does not unduly favor one filesystem 190 or operating system over another. 192 o Designed for protocol extensions. 194 The protocol is designed to accept standard extensions that do 195 not compromise backward compatibility. 197 2. RPC and Security Flavor 199 The NFS version 4 protocol is a Remote Procedure Call (RPC) 200 application that uses RPC version 2 and the corresponding eXternal 201 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 202 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 203 the mechanism to deliver stronger security to NFS version 4. 205 2.1. Ports and Transports 207 Historically, NFS version 2 and version 3 servers have resided on 208 UDP/TCP port 2049. Port 2049 is a IANA registered port number for NFS 209 and therefore will continue to be used for NFS version 4. Using the 210 well known port for NFS services means the NFS client will not need 211 to use the RPC binding protocols as described in [RFC1833]; this will 212 allow NFS to transit firewalls. 214 The NFS server SHOULD offer its RPC service via TCP as the primary 215 transport. The server SHOULD also provide UDP for RPC service. The 216 NFS client SHOULD also have a preference for TCP usage but may supply 217 a mechanism to override TCP in favor of UDP as the RPC transport. 219 2.2. Security Flavors 221 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 222 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 223 additional security flavor of RPCSEC_GSS has been introduced which 224 uses the functionality of GSS-API [RFC2078]. This allows for the use 225 of varying security mechanisms by the RPC layer without the 226 additional implementation overhead of adding RPC security flavors. 227 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 228 enable the mandatory security mechanism. The flavors AUTH_NONE, 229 AUTH_SYS, and AUTH_DH MAY be implemented as well. 231 2.2.1. Security mechanisms for NFS version 4 233 The use of RPCSEC_GSS requires selection of: mechanism, quality of 234 protection, and service (authentication, integrity, privacy). The 235 remainder of this document will refer to these three parameters of 236 the RPCSEC_GSS security as the security triple. 238 2.2.1.1. Kerberos V5 as security triple 240 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 241 implemented and provide the following security triples. 243 columns: 245 1 == number of pseudo flavor 246 2 == name of pseudo flavor 247 3 == mechanism's OID 248 4 == mechanism's algorithm(s) 249 5 == RPCSEC_GSS service 251 1 2 3 4 5 252 ----------------------------------------------------------------------- 253 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 254 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 255 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 256 for integrity, 257 and 56 bit DES 258 for privacy. 260 This section will be expanded to include the pertinent 261 details from draft-ietf-nfsv4-nfssec-00.txt. 263 2.2.1.2. 265 Another GSS-API mechanism will need to be specified here 266 along with the corresponding security triple(s). 268 2.3. Security Negotiation 270 With the NFS version 4 server potentially offering multiple security 271 mechanisms, the client will need a way to determine or negotiate 272 which mechanism is to be used for its communication with the server. 273 The NFS server may have multiple points within its file system name 274 space that are available for use by NFS clients. In turn the NFS 275 server may be configured such that each of these entry points may 276 have different or multiple security mechanisms in use. 278 The security negotiation between client and server must be done with 279 a secure channel to eliminate the possibility of a third party 280 intercepting the negotiation sequence and forcing the client and 281 server to choose a lower level of security than required/desired. 283 2.3.1. Security Error 285 Based on the assumption that each NFS version 4 client and server 286 must support a minimum set of security (i.e. Kerberos-V5 under 287 RPCSEC_GSS, ), the NFS client will start its 288 communication with the server with one of the minimal security 289 triples. During communication with the server, the client may 290 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 291 server to notify the client that the security triple currently being 292 used is not appropriate for access to the server's file system 293 resources. The client is then responsible for determining what 294 security triples are available at the server and choose one which is 295 appropriate for the client. 297 2.3.2. SECINFO 299 The new procedure SECINFO (see SECINFO procedure definition) will 300 allow the client to determine, on a per filehandle basis, what 301 security triple is to be used for server access. In general, the 302 client will not have to use the SECINFO procedure except during 303 initial communication with the server or when the client crosses 304 policy boundaries at the server. It could happen that the server's 305 policies change during the client's interaction therefore forcing the 306 client to negotiate a new security triple. 308 3. File handles 310 The file handle in the NFS protocol is a per server unique identifier 311 for a file system object. The contents of the file handle are opaque 312 to the client. Therefore, the server is responsible for translating 313 the file handle to an internal representation of the file system 314 object. Since the file handle is the client's reference to an object 315 and the client may cache this reference, the server should not reuse 316 a file handle for another file system object. If the server needs to 317 reuse a file handle value, the time elapsed before reuse SHOULD be 318 large enough that it is likely the client no longer has a cached copy 319 of the reused file handle value. 321 3.1. Obtaining the First File Handle 323 The procedures of the NFS protocol are defined in terms of one or 324 more file handles. Therefore, the client needs a file handle to 325 initiate communication with the server. With NFS version 2 [RFC1094] 326 and NFS version 3 [RFC1813], there exists an ancillary protocol to 327 obtain this first file handle. The MOUNT protocol, RPC program 328 number 100005, provides the mechanism of translating a string based 329 file system path name to a file handle which can then be used by the 330 NFS protocols. 332 The MOUNT protocol has deficiencies in the area of security and use 333 via firewalls. This is one reason that the use of the public file 334 handle was introduced [RFC2054] [RFC2055]. With the use of public 335 file handle in combination with the LOOKUP procedure in NFS version 2 336 and 3, it has been demonstrated that the MOUNT protocol is 337 unnecessary for viable interaction between NFS client and server. 339 Therefore, NFS version 4 will not use an ancillary protocol for 340 translation from string based path names to a file handle. Two 341 special file handles will be used as starting points for the NFS 342 client. 344 3.1.1. Root File Handle 346 The first of the special file handles is the ROOT file handle. The 347 ROOT file handle does not have a special file handle value as does 348 the public file handle. The ROOT file handle is the "conceptual" 349 root of the file system name space at the NFS server. The client 350 uses or starts with the ROOT file handle by employing the PUTROOTFH 351 procedure. The PUTROOTFH procedure instructs the server to set the 352 "current" file handle to the ROOT of the server's file tree. Once 353 this PUTROOTFH procedure is used, the client can then traverse the 354 entirety of the server's file tree with the LOOKUP procedure. A 355 complete discussion of the server name space is in section 6, "NFS 356 Server Name Space". 358 3.1.2. Public File Handle 360 Unlike the root file handle, the public file handle is represented by 361 a reserved or special value of the file handle. NFS version 4 362 defines the file handle as a variable length array of bytes (see 363 section 4, "Basic Data Types"). The public file handle is the 'zero' 364 file handle or in other words a file handle with a array length of 365 zero. 367 Again unlike the root file handle, the public file handle may be 368 bound or represent an arbitrary file system object at the server. 369 The server is responsible for this binding. It may be that the 370 public file handle and the root file handle refer to the same file 371 system object. However, it is up to the administrative software at 372 the server and the policies of the server administrator to define the 373 binding of public file handle and server file system object. The 374 client may not make any assumptions about this binding. 376 3.2. File Handle Types 378 In NFS version 2 and 3, there was one type of file handle with a 379 single set of semantics. NFS version 4 introduces a new type of file 380 handle in an attempt to accommodate certain server environments. The 381 first type of file handle is 'persistent'. The semantics of a 382 persistent file handle are the same as the file handles of NFS 383 version 2 and 3. The second or new type of file handle is the 384 'volatile' file handle. 386 The volatile file handle type is being introduced to address server 387 functionality or implementation issues which prevent correct or 388 feasible implementation of a persistent file handle. Some server 389 environments do not provide a file system level invariant that can be 390 used to construct a persistent file handle. The underlying server 391 file system may not provide the invariant or the server's file system 392 APIs may not provide access to the needed invariant. Volatile file 393 handles may ease the implementation of server functionality such as 394 hierarchical storage management or file system reorganization or 395 migration. However, the volatile file handle increases the 396 implementation burden for the client but this increased burden is 397 deemed acceptable based on the overall gains achieved by the 398 protocol. 400 Since the client will have different paths of logic to handle 401 persistent and volatile file handles, a file attribute is defined 402 which may be used by the client to determine the file handle types 403 being returned by the server. 405 3.2.1. General Properties of a File Handle 407 The file handle contains all the information the server needs to 408 distinguish an individual file. To the client, the file handle is 409 opaque. The client stores file handles for use in a later request and 410 can compare two file handles from the same server for equality by 411 doing a byte-by-byte comparison, but MUST NOT otherwise interpret the 412 contents of file handles. If two file handles from the same server 413 are equal, they MUST refer to the same file, but if they are not 414 equal, no conclusions can be drawn. Servers SHOULD try to maintain a 415 one-to-one correspondence between file handles and files but this is 416 not required. Clients MUST only use file handle comparisons only to 417 improve performance, not for correct behavior. 419 As an example, in the case that two different path names when 420 traversed at the server terminate at the same file system object, the 421 server SHOULD return the same file handle for each path. This can 422 occur if a hard link is used to create two file names which refer to 423 the same underlying file object and associated data. For example, if 424 paths /a/b/c and /a/d/c refer to the same file, the server SHOULD 425 return the same file handle for both path names traversals. 427 3.2.2. Persistent File Handle 429 A persistent file handle is defined as having a persistent value for 430 the lifetime of the file system object to which it refers. Once the 431 server creates the file handle for a file system object, the server 432 MUST return the same file handle for the object for the lifetime of 433 the object. If the server restarts or reboots, the NFS server must 434 honor and present the same file handle value as it did in the 435 server's previous instantiation. 437 The persistent file handle will be become stale or invalid when the 438 file system object is removed. When the server is presented with a 439 persistent file handle that refers to a deleted object, it MUST 440 return an error of NFS4ERR_STALE. A file handle may become stale 441 when the file system containing the object is no longer available. 442 The file system may become unavailable if it exists on removable 443 media and the media is no longer available at the server or the file 444 system in whole has been destroyed or the file system has simply been 445 removed from the server's name space (i.e. unmounted in a Unix 446 environment). 448 3.2.3. Volatile File Handle 450 A volatile file handle does not share the same longevity attributes 451 of the persistent file handle. The server may determine that a 452 volatile file handle is no longer valid at many different points in 453 time. If the server can definitively determine that a volatile file 454 handle refers to an object that has been removed, the server should 455 return NFS4ERR_STALE to the client (as is the case for persistent 456 file handles). In all other cases where the server determines that a 457 volatile file handle can no longer be used, it should return an error 458 of NFS4ERR_EXPIRED. 460 The following table shows the most common points at which a volatile 461 file handle may expire. This table represents the view from the 462 client's perspective and as such provides columns for when the file 463 may be open or closed by the client. 465 Server Provides Persistent or Volatile File Handle 466 File Open File Closed 467 ___________________________________________________________________ 468 Restart of Server (note 4) P / V P / V 469 Fileset Migration (note 5) P / V P / V 470 SHARE/LOCK recovery P / V N/A (note 1) 471 Client RENAMEs object P / V P / V 472 Client RENAMEs path to object P / V P / V 473 Other client RENAMEs object P / V P / V 474 Other client RENAMEs path to object P / V P / V 475 Client REMOVEs object P / V (note 2) P / V 476 Other client REMOVEs object P / V N/A (note 3) 478 Note 1 479 If the file is not open, persistence of the file handle is not 480 applicable for the recovery of SHARE/LOCK. 482 Note 2 483 With NFS version 2 and 3, when the client removes a file it has 484 open it follows the convention of RENAMEing the file to '.nfsXXXX' 485 until the file is closed. At this point the REMOVE is done at the 486 server. 488 If this same model is used for v4 then this entry will be 489 'N/A'. 491 Note 3 492 If the file is not open by the client, then it should not expect 493 any cached file handle to be valid. 495 Note 4 496 The restart of the NFS server signifies when the operating system 497 or NFS software is (re)started. This also includes High 498 Availability configurations where a separate operating system 499 instantiation acquires ownership of the file system resources and 500 network resources (i.e. disks and IP addresses). 502 Note 5 503 Fileset migration occurs when a the ownership of file system 504 resources are transfered from one server to another without a 505 transfer of ownership of the network resources. So this differs 506 from the High Availability scenario. This also includes the move 507 of a file system resources within the same server such that the 508 fsid value is different. 510 The fileset migration entry is a place holder until a file 511 set migration proposal has been fully evaluated and decided 512 upon. 514 3.2.4. One Method of Constructing a Volatile File Handle 516 As mentioned, in some instances a file handle is stale (no longer 517 valid, perhaps because the file was removed from the server), or it 518 is expired (the underlying file is valid, but since the file handle 519 is volatile, it may have expired). Thus the server needs to be able 520 to return NFS4ERR_STALE in the former case, and NFS4ERR_EXPIRED in 521 the latter case. This can be done by careful construction of the 522 volatile file handle. One possible implementation follows. 524 A volatile file handle, while opaque to the client could contain: 526 [volatile bit = 1 | server boot time | slot | generation number] 528 o slot is an index in the server volatile file handle table 530 o generation number is the generation number for the table 531 entry/slot 533 If the server boot time is less than the current server boot time, 534 return NFS4ERR_EXPIRED. If slot is out of range, return 535 NFS4ERR_EXPIRED. If the generation number does not match, return 536 NFS4ERR_EXPIRED. 538 When the server reboots, the table is gone (it is volatile). 540 If volatile bit is 0, then it is a persistent file handle with a 541 different structure following it. 543 3.3. Client Recovery from File Handle Expiration 545 With the introduction of the volatile file handle, the client must 546 take on additional responsibility so that it may prepare itself to 547 recover from the expiration of a volatile file handle. If the server 548 is return persistent file handles, the client does not need these 549 additional steps. 551 For volatile file handles, most commonly the client will need to 552 store the component names leading up to and including the file system 553 object in question. With these names, the client should be able to 554 recover by finding a file handle in the name space that is still 555 available or by starting at the root of the server's file system name 556 space. 558 If the expired file handle refers to an object that has been removed 559 from the file system, obviously the client will not be able to 560 recover from the expired file handle. 562 It is also possible that the expired file handle, refers to a file 563 that has been renamed. If the file was renamed by another client, 564 again it is possible that the original client will not be able to 565 recover. However, in the case that the client itself is renaming the 566 file and the file is open, it is possible that the client may be able 567 to recover. The client can determine the new path name based on the 568 processing of the rename request. The client can then regenerate the 569 new file handle based on the new path name. The client could also 570 use the compound operation mechanism to construct a set of operations 571 like: 572 RENAME A B 573 LOOKUP B 574 GETFH 576 4. Basic Data Types 578 Arguments and results from operations will be described in terms of 579 basic XDR types defined in [RFC1832]. The following data types will 580 be defined in terms of basic XDR types: 582 filehandle: opaque <128> 584 An NFS version 4 filehandle. A filehandle with zero length is 585 recognized as a "public" filehandle. 587 utf8string: opaque <> 589 A counted array of octets that contains a UTF-8 string. 591 Note: Section 11, Internationalization, covers the rational of 592 using UTF-8. 594 bitmap: uint32 <> 596 A counted array of 32 bit integers used to contain bit values. 597 The position of the integer in the array that contains bit n can 598 be computed from the expression (n / 32) and its bit within that 599 integer is (n mod 32). 601 0 1 602 +-----------+-----------+-----------+-- 603 | count | 31 .. 0 | 63 .. 32 | 604 +-----------+-----------+-----------+-- 606 createverf: opaque<8> 608 Verify used for exclusive create semantics 610 nfstime4 611 struct nfstime4 { 612 int64_t seconds; 613 uint32_t nseconds; 614 } 616 The nfstime4 structure gives the number of seconds and 617 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 618 Universal Time (UTC). Values greater than zero for the seconds 619 field denote dates after the 0 hour January 1, 1970. Values 620 less than zero for the seconds field denote dates before the 0 621 hour January 1, 1970. In both cases, the nseconds field is to 622 be added to the seconds field for the final time representation. 623 For example, if the time to be represented is one-half second 624 before 0 hour January 1, 1970, the seconds field would have a 625 value of negative one (-1) and the nseconds fields would have a 626 value of one-half second (500000000). Values greater than 627 999,999,999 for nseconds are considered invalid. 629 This data type is used to pass time and date information. A 630 server converts to and from local time when processing time 631 values, preserving as much accuracy as possible. If the 632 precision of timestamps stored for a file system object is less 633 than defined, loss of precision can occur. An adjunct time 634 maintenance protocol is recommended to reduce client and server 635 time skew. 637 specdata4 638 struct specdata4 { 639 uint32_t specdata1; 640 uint32_t specdata2; 641 } 643 This data type represents additional information for the device 644 file types NFCHR and NFBLK. 646 5. File Attributes 648 To meet the NFS Version 4 requirements of extensibility and increased 649 interoperability with non-Unix platforms, attributes must be handled 650 in a more flexible manner. The NFS Version 3 fattr3 structure 651 contained a fixed list of attributes that not all clients and servers 652 are able to support or care about, which cannot be extended as new 653 needs crop up, and which provides no way to indicate non-support. 654 With NFS Version 4, the client will be able to ask what attributes 655 the server supports, and will be able to request only those 656 attributes in which it is interested. 658 To this end, attributes will be divided into three groups: mandatory, 659 recommended and named. Both mandatory and recommended attributes are 660 supported in the NFS V4 protocol by a specific and well-defined 661 encoding, and are identified by number. They are requested by 662 setting a bit in the bit vector sent in the GETATTR request; the 663 server response includes a bit vector to list what attributes were 664 returned in response. New mandatory or recommended attributes may be 665 added to the NFS protocol between revisions by publishing a 666 standards-track RFC which allocates a new attribute number value and 667 defines the encoding for the attribute. 669 Named attributes are accessed by the new OPENATTR operation, which 670 accesses a hidden directory of attributes associated with a 671 filesystem object. OPENATTR takes a filehandle for the object and 672 returns the filehandle for the attribute hierarchy, which is a 673 directory object accessible by LOOKUP or READDIR, and which contains 674 files whose names represent the named attributes and whose data bytes 675 are the value of the attribute. For example: 677 LOOKUP "foo" ; look up file 678 GETATTR attrbits 679 OPENATTR ; access foo's named attributes 680 LOOKUP "x11icon" ; look up specific attribute 681 READ 0,4096 ; read stream of bytes 683 Named attributes are intended primarily for data needed by 684 applications rather than by an NFS client implementation per se; NFS 685 implementors are strongly encouraged to define their new attributes 686 as recommended attributes by bringing them to the working group. 688 The set of attributes which are classified as mandatory is 689 deliberately small, since servers must do whatever it takes to 690 support them. The recommended attributes may be unsupported, though 691 a server should support as many as it can. Attributes are deemed 692 mandatory if the data is both needed by a large number of clients and 693 is not otherwise reasonably computable by the client when support is 694 not provided on the server. 696 5.1. Mandatory Attributes 698 These MUST be supported by every NFS Version 4 client and server in 699 order to ensure a minimum level of interoperability. The server must 700 store and return these attributes, and the client must be able to 701 function with an attribute set limited to these attributes, though 702 some operations may be impaired or limited in some ways in this case. 703 A client may ask for any of these attributes to be returned by 704 setting a bit in the GETATTR request, and the server must return 705 their value. 707 5.2. Recommended Attributes 709 These attributes are understood well enough to warrant support in the 710 NFS Version 4 protocol, though they may not be supported on all 711 clients and servers. A client may ask for any of these attributes to 712 be returned by setting a bit in the GETATTR request, but must be able 713 to deal with not receiving them. A client may ask for the set of 714 attributes the server supports and should not request attributes the 715 server does not support. A server should be tolerant of requests for 716 unsupported attributes, and simply not return them, rather than 717 considering the request an error. It is expected that servers will 718 support all attributes they comfortably can, and only fail to support 719 attributes which are difficult to support in their operating 720 environments. A server should provide attributes whenever they don't 721 have to "tell lies" to the client. For example, a file modification 722 time should be either an accurate time or should not be supported by 723 the server. This will not always be comfortable to clients but it 724 seems that the client has a better ability to fabricate or construct 725 an attribute or do without. 727 Most attributes from NFS V3's FSINFO, FSSTAT and PATHCONF procedures 728 have been added as recommended attributes, so that filesystem info 729 may be collected via the filehandle of any object the filesystem. 730 This renders those procedures unnecessary in NFS V4. If a server 731 supports any per-filesystem attributes, it must support the fsid 732 attribute so that the client may always determine when filesystems 733 are crossed so that it can work correctly with these attributes. 735 5.3. Named Attributes 737 These attributes are not supported by direct encoding in the NFS 738 Version 4 protocol but are accessed by string names rather than 739 numbers and correspond to an uninterpreted stream of bytes which are 740 stored with the filesystem object. The namespace for these 741 attributes may be accessed by using the OPENATTR operation to get a 742 filehandle for a virtual "attribute directory" and using READDIR and 743 LOOKUP operations on this filehandle. Named attributes may then be 744 examined or changed by normal READ and WRITE and CREATE operations on 745 the filehandles returned from READDIR and LOOKUP. Named attributes 746 may have attributes, for example, a security label may have access 747 control information in its own right. 749 It is recommended that servers support arbitrary named attributes. A 750 client should not depend on the ability to store any named attributes 751 in the server's filesystem. If a server does support named 752 attributes, a client which is also able to handle them should be able 753 to copy a file's data and meta-data with complete transparency from 754 one location to another; this would imply that there should be no 755 attribute names which will be considered illegal by the server. 757 Names of attributes will not be controlled by a standards body. 758 However, vendors and application writers are encouraged to register 759 attribute names and the interpretation and semantics of the stream of 760 bytes via informational RFC so that vendors may interoperate where 761 common interests exist. 763 5.4. Mandatory Attributes - Definitions 765 Name # DataType Access Description 766 __________________________________________________________________ 767 supp_attr 0 bitmap READ 768 The bit vector which 769 would retrieve all 770 mandatory and 771 recommended attributes 772 which may be requested 773 for this object. 775 The client must ask 776 this question to 777 request correct 778 attributes. 780 object_type 1 nfs4_ftype READ 781 The type of the object 782 (file, directory, 783 symlink) 785 The client cannot 786 handle object 787 correctly without 788 type. 790 persistent_fh 2 boolean READ 791 Is the filehandle for 792 this object 793 persistent? 795 Server should know if 796 the file handles being 797 provided are 798 persistent or not. If 799 the server is not able 800 to make this 801 determination, then it 802 can choose volatile or 803 non-persistent. 805 change 3 uint64 READ 806 A value created by the 807 server that the client 808 can use to determine 809 if a file data, 810 directory contents or 811 attributes have been 812 modified. The server 813 can just return the 814 file mtime in this 815 field though if a more 816 precise value exists 817 then it can be 818 substituted, for 819 instance, a sequence 820 number. 822 Necessary for any 823 useful caching, likely 824 to be available. 826 object_size 4 uint64 R/W 827 The size of the object 828 in bytes. 830 Could be very 831 expensive to derive, 832 likely to be 833 available. 835 link_support 5 boolean READ 836 Does the object's 837 filesystem supports 838 hard links? 840 Server can easily 841 determine if links are 842 supported. 844 symlink_support 6 boolean READ 845 Does the object's 846 filesystem supports 847 symbolic links? 849 Server can easily 850 determine if links are 851 supported. 853 named_attr 7 boolean READ 854 Does this object have 855 named attributes? 857 fsid.major 8 uint64 READ 858 Unique filesystem 859 identifier for the 860 filesystem holding 861 this object. 863 fsid.minor 9 uint64 READ 864 Unique filesystem 865 identifier within the 866 fsid.major filesystem 867 identifier for the 868 filesystem holding 869 this object. 871 5.5. Recommended Attributes - Definitions 873 Name # Data Type Access Description 874 ___________________________________________________________________ 875 ACL 10 nfsacl4 R/W 876 The access control 877 list for the object. 878 [The nature and format 879 of ACLs is still to be 880 determined.] 882 archive 11 boolean R/W 883 Whether or not this 884 file has been archived 885 since the time of last 886 modification 887 (deprecated in favor 888 of backup_time). 890 cansettime 12 boolean READ 891 Whether or not this 892 object's filesystem 893 can fill in the times 894 on a SETATTR request 895 without an explicit 896 time. 898 case_insensitive 13 boolean READ 899 Are filename 900 comparisons on this 901 filesystem case 902 insensitive? 904 case_preserving 14 boolean READ 905 Is filename case on 906 this filesystem 907 preserved? 909 chown_restricted 15 boolean READ 910 Will a request to 911 change ownership be 912 honored? 914 filehandle 16 nfs4_fh READ 915 The filehandle of this 916 object (primarily for 917 readdir requests). 919 fileid 17 uint64 READ 920 A number uniquely 921 identifying the file 922 within the filesystem. 924 files_avail 18 uint64 READ 925 File slots available 926 to this user on the 927 filesystem containing 928 this object - this 929 should be the smallest 930 relevant limit. 932 files_free 19 uint64 READ 933 Free file slots on the 934 filesystem containing 935 this object - this 936 should be the smallest 937 relevant limit. 939 files_total 20 uint64 READ 940 Total file slots on 941 the filesystem 942 containing this 943 object. 945 hidden 21 boolean R/W 946 Is file considered 947 hidden? 949 homogeneous 22 boolean READ 950 Whether or not this 951 object's filesystem is 952 homogeneous, i.e. 953 whether pathconf is 954 the same for all 955 filesystem objects. 957 maxfilesize 23 uint64 READ 958 Maximum supported file 959 size for the 960 filesystem of this 961 object. 963 maxlink 24 uint32 READ 964 Maximum number of 965 links for this object. 967 maxname 25 uint32 READ 968 Maximum filename size 969 supported for this 970 object. 972 maxread 26 uint64 READ 973 Maximum read size 974 supported for this 975 object. 977 maxwrite 27 uint64 READ 978 Maximum write size 979 supported for this 980 object. This 981 attribute SHOULD be 982 supported if the file 983 is writable. Lack of 984 this attribute can 985 lead to the client 986 either wasting 987 bandwidth or not 988 receiving the best 989 performance. 991 mime_type 28 utf8<> R/W 992 MIME body type/subtype 993 of this object. 995 mode 29 uint32 R/W 996 Unix-style permission 997 bits for this object 998 (deprecated in favor 999 of ACLs) 1001 no_trunc 30 boolean READ 1002 If a name longer than 1003 name_max is used, will 1004 an error be returned 1005 or will the name be 1006 truncated? 1008 numlinks 31 uint32 READ 1009 Number of links to 1010 this object. 1012 owner 32 utf8<> R/W 1013 The string name of the 1014 owner of this object. 1016 owner_group 33 utf8<> R/W 1017 The string name of the 1018 group of the owner of 1019 this object. 1021 quota_hard 34 uint64 READ 1022 Number of bytes of 1023 disk space beyond 1024 which the server will 1025 decline to allocate 1026 new space. 1028 quota_soft 35 uint64 READ 1029 Number of bytes of 1030 disk space at which 1031 the client may choose 1032 to warn the user about 1033 limited space. 1035 quota_used 36 uint64 READ 1036 Number of bytes of 1037 disk space occupied by 1038 the owner of this 1039 object on this 1040 filesystem. 1042 rawdev 37 specdata4 READ 1043 Raw device identifier. 1045 space_avail 38 uint64 READ 1046 Disk space in bytes 1047 available to this user 1048 on the filesystem 1049 containing this object 1050 - this should be the 1051 smallest relevant 1052 limit. 1054 space_free 39 uint64 READ 1055 Free disk space in 1056 bytes on the 1057 filesystem containing 1058 this object - this 1059 should be the smallest 1060 relevant limit. 1062 space_total 40 uint64 READ 1063 Total disk space in 1064 bytes on the 1065 filesystem containing 1066 this object. 1068 space_used 41 uint64 READ 1069 Number of filesystem 1070 bytes allocated to 1071 this object. 1073 system 42 boolean R/W 1074 Whether or not this 1075 file is a system file. 1077 time_access 43 nfstime4 R/W 1078 The time of last 1079 access to the object. 1081 time_backup 44 nfstime4 R/W 1082 The time of last 1083 backup of the object. 1085 time_create 45 nfstime4 R/W 1086 The time of creation 1087 of the object. This 1088 attribute does not 1089 have any relation to 1090 the traditional Unix 1091 file attribute 'ctime' 1092 or 'change time'. 1094 time_delta 46 nfstime4 READ 1095 Smallest useful server 1096 time granularity. 1098 time_metadata 47 nfstime4 R/W 1099 The time of last 1100 meta-data modification 1101 of the object. 1103 time_modify 48 nfstime4 R/W 1104 The time since the 1105 epoch of last 1106 modification to the 1107 object. 1109 version 49 utf8<> R/W 1110 Version number of this 1111 document. 1113 volatility 50 nfstime4 READ 1114 Approximate time until 1115 next expected change 1116 on this filesystem, as 1117 a measure of 1118 volatility. 1120 6. NFS Server Namespace 1122 6.1. Server Exports 1124 On a UNIX server the name-space describes all the files reachable by 1125 pathnames under the root directory "/". On a Windows NT server the 1126 name-space constitutes all the files on disks named by mapped disk 1127 letters. NFS server administrators rarely make the entire server's 1128 file-system name-space available to NFS clients. Typically, pieces 1129 of the name-space are made available via an "export" feature. The 1130 root filehandle for each export is obtained through the MOUNT 1131 protocol; the client sends a string that identifies the export of 1132 name-space and the server returns the root filehandle for it. The 1133 MOUNT protocol supports an EXPORTS procedure that will enumerate the 1134 server's exports. 1136 6.2. Browsing Exports 1138 The NFS version 4 protocol provides a root filehandle that clients 1139 can use to obtain filehandles for these exports via a multi-component 1140 LOOKUP. A common user experience is to use a graphical user 1141 interface (perhaps a file "Open" dialog window) to find a file via 1142 progressive browsing through a directory tree. The client must be 1143 able to move from one export to another export via single-component, 1144 progressive LOOKUP operations. 1146 This style of browsing is not well supported by NFS version 2 and 3 1147 protocols. The client expects all LOOKUP operations to remain within 1148 a single server file-system, i.e. the device attribute will not 1149 change. This prevents a client from taking name-space paths that 1150 span exports. 1152 An automounter on the client can obtain a snapshot of the server's 1153 name-space using the EXPORTS procedure of the MOUNT protocol. If it 1154 understands the server's pathname syntax, it can create an image of 1155 the server's name-space on the client. The parts of the name-space 1156 that are not exported by the server are filled in with a "pseudo 1157 file-system" that allows the user to browse from one mounted file- 1158 system to another. There is a drawback to this representation of the 1159 server's name-space on the client: it is static. If the server 1160 administrator adds a new export the client will be unaware of it. 1162 6.3. Server Pseudo File-System 1164 NFS version 4 servers avoid this name-space inconsistency by 1165 presenting all the exports within the framework of a single server 1166 name-space. An NFS version 4 client uses LOOKUP and READDIR 1167 operations to browse seamlessly from one export to another. Portions 1168 of the server name-space that are not exported are bridged via a 1169 "pseudo file-system" that provides a view only of exported 1170 directories. The pseudo file-system has a unique fsid and behaves 1171 like a normal, read-only file-system. 1173 6.4. Multiple Roots 1175 DOS, Windows 95, 98 and NT are sometimes described as having 1176 "multiple roots". File-Systems are commonly represented as disk 1177 letters. MacOS represents file-systems as top-level names. NFS 1178 version 4 servers for these platforms can construct a pseudo file- 1179 system above these root names so that disk letters or volume names 1180 are simply directory names in the pseudo-root. 1182 6.5. Filehandle Volatility 1184 The nature of the server's pseudo file-system is that it is a logical 1185 representation of file-system(s) available from the server. 1186 Therefore, the pseudo file-system is most likely constructed 1187 dynamically when the NFS version 4 is first instantiated. It is 1188 expected the pseudo file-system may not have an on-disk counterpart 1189 from which persistent filehandles could be constructed. Even though 1190 it is preferable that the server provide persistent filehandles for 1191 the pseudo file-system, the NFS client should expect that pseudo 1192 file-system file-handles are volatile. This can be confirmed by 1193 checking the associated "persistent_fh" attribute for those 1194 filehandles in question. If the filehandles are volatile, the NFS 1195 client must be prepared to recover a filehandle value (i.e. with a v4 1196 multi-component LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 1198 6.6. Exported Root 1200 If the server's root file-system is exported, it might be easy to 1201 conclude that a pseudo-file-system is not needed. This would be 1202 wrong. Assume the following file-systems on a server: 1204 / disk1 (exported) 1205 /a disk2 (not exported) 1206 /a/b disk3 (exported) 1208 Because disk2 is not exported, disk3 cannot be reached with simple 1209 LOOKUPs. The server must bridge the gap with a pseudo-file-system. 1211 6.7. Mount Point Crossing 1213 The server file-system environment may constructed in such a way that 1214 one file-system contains a directory which is 'covered' or mounted 1215 upon by a second file-system. For example: 1217 /a/b (file system 1) 1218 /a/b/c/d (file system 2) 1220 The pseudo file-system for this server may be constructed to look 1221 like: 1223 / (place holder/not exported) 1224 /a/b (file system 1) 1225 /a/b/c/d (file system 2) 1227 It is the server's responsibility to present the pseudo file-system 1228 that is complete to the client. If the client sends a lookup request 1229 for the path "/a/b/c/d", the server's response is the filehandle of 1230 the file system "/a/b/c/d". In previous versions of NFS, the server 1231 would respond with the directory "/a/b/d/d" within the file-system 1232 "/a/b". 1234 The NFS client will be able to determine if it crosses a server mount 1235 point by a change in the value of the "fsid" attribute. 1237 6.8. Summary 1239 NFS version 4 provides LOOKUP and READDIR operations for browsing of 1240 NFS file-systems. These operations are also used to browse server 1241 exports. A v4 server supports export browsing by including exported 1242 directories in a pseudo-file-system. A browsing client can cross 1243 seamlessly between a pseudo-file-system and a real, exported file- 1244 system. Clients must support volatile filehandles and recognize 1245 mount point crossing of server file-systems. 1247 7. File Locking 1249 Integrating locking into NFS necessarily causes it to be state-full, 1250 with the invasive nature of "share" file locks it becomes 1251 substantially more dependent on state than the traditional 1252 combination of NFS and NLM [XNFS]. There are three components to 1253 making this state manageable: 1255 o Clear division between client and server 1257 o Ability to reliably detect inconsistency in state between client 1258 and server 1260 o Simple and robust recovery mechanisms 1262 In this model, the server owns the state information. The client 1263 communicates its view of this state to the server as needed. The 1264 client is also able to detect inconsistent state before modifying a 1265 file. 1267 To support Windows "share" locks, it is necessary to atomically open 1268 or create files. Having a separate share/unshare operation will not 1269 allow correct implementation of the Windows OpenFile API. In order 1270 to correctly implement share semantics, the existing mechanisms used 1271 when a file is opened or created (LOOKUP, CREATE, ACCESS) need to be 1272 replaced. NFS V4 will have an OPEN procedure that subsumes the 1273 functionality of LOOKUP, CREATE, and ACCESS. However, because many 1274 operations require a file handle, the traditional LOOKUP is preserved 1275 to map a file name to file handle without establishing state on the 1276 server. Policy of granting access or modifying files is managed by 1277 the server based on the client's state. It is believed that these 1278 mechanisms can implement policy ranging from advisory only locking to 1279 full mandatory locking. While ACCESS is just a subset of OPEN, the 1280 ACCESS procedure is maintained as a lighter weight mechanism. 1282 7.1. Definitions 1284 Lock The term "lock" will be used to refer to both record 1285 (byte-range) locks as well as file (share) locks unless 1286 specifically stated otherwise. 1288 Client Throughout this proposal the term "client" is used to 1289 indicate the entity that maintains a set of locks on behalf 1290 of one or more applications. The client is responsible for 1291 crash recovery of those locks it manages. Multiple clients 1292 may share the same transport and multiple clients may exist 1293 on the same network node. 1295 Clientid A 64-bit quantity returned by a server that uniquely 1296 corresponds to a client supplied Verifier and ID. 1298 Lease An interval of time defined by the server for which the 1299 client is irrevokeably granted a lock. At the end of a 1300 lease period the lock may be revoked if the lease has not 1301 been extended. The lock must be revoked if a conflicting 1302 lock has been granted after the lease interval. All leases 1303 granted by a server have the same fixed interval. 1305 Stateid A 64-bit quantity returned by a server that uniquely 1306 defines the locking state granted by the server for a 1307 specific lock owner for a specific file. A stateid 1308 composed of all bits 0 or all bits 1 have special meaning 1309 and are reserved. 1311 Verifier A 32-bit quantity generated by the client that the server 1312 can use to determine if the client has restarted and lost 1313 all previous lock state. 1315 7.2. Locking 1317 It is assumed that manipulating a lock is rare when compared to I/O 1318 operations. It is also assumed that crashes and network partitions 1319 are relatively rare. Therefore it is important that I/O operations 1320 have a light weight mechanism to indicate if they possess a held 1321 lock. A lock request contains the heavy weight information required 1322 to establish a lock and uniquely define the lock owner. 1324 The following sections describe the transition from the heavy weight 1325 information to the eventual stateid used for most client and server 1326 locking and lease interactions. 1328 7.2.1. Client ID 1330 For each LOCK request, the client must identify itself to the server. 1331 This is done in such a way as to allow for correct lock 1332 identification and crash recovery. Client identification is 1333 accomplished with two values. 1335 o A verifier that is used to detect client reboots. 1337 o A variable length opaque array to uniquely define a client. 1339 For an operating system this may be a fully qualified host 1340 name or IP address, and for a user level NFS client it may 1341 additionally contain a process id or other unique sequence. 1343 The data structure for the Client ID would then appear as: 1344 struct nfs_client_id { 1345 opaque verifier[4]; 1346 opaque id<>; 1347 }: 1349 It is possible through the mis-configuration of a client or the 1350 existence of a rogue client that two clients end up using the same 1351 nfs_client_id. This situation is avoided by 'negotiating' the 1352 nfs_client_id between client and server with the use of the 1353 SETCLIENTID. The following describes the two scenarios of 1354 negotiation. 1356 1 Client has never connected to the server 1358 In this case the client generates an nfs_client_id and 1359 unless another client has the same nfs_client_id.id field, 1360 the server accepts the request. The server also records the 1361 principal (or principal to uid mapping) from the credential 1362 in the RPC request that contains the nfs_client_id 1363 negotiation request. 1365 Two clients might still use the same nfs_client_id.id due 1366 to perhaps configuration error (say a High Availability 1367 configuration where the nfs_client_id.id is derived from 1368 the ethernet controller address and both systems have the 1369 same address). In this case, nfs4err can be a switched 1370 union that returns in addition to NFS4ERR_CLID_IN_USE, the 1371 network address (the rpcbind netid and universal address) 1372 of the client that is using the id. 1374 2 Client is re-connecting to the server after a client reboot 1376 In this case, the client still generates an nfs_client_id 1377 but the nfs_client_id.id field will be the same as the 1378 nfs_client_id.id generated prior to reboot. If the server 1379 finds that the principal/uid is equal to the previously 1380 "registered" nfs_client_id.id, then locks associated with 1381 the old nfs_client_id are immediately released. If the 1382 principal/uid is not equal, then this is a rogue client and 1383 the request is returned in error. For more discussion of 1384 crash recovery semantics, see the section on "Crash 1385 Recovery" 1387 In both cases, upon success, NFS4_OK is returned. To help reduce the 1388 amount of data transferred on OPEN and LOCK, the server will also 1389 return a unique 64-bit clientid value that is a short hand reference 1390 to the nfs_client_id values presented by the client. From this point 1391 forward, the client can use the clientid to refer to itself. 1393 7.2.2. nfs_lockowner and stateid definition 1395 When requesting a lock, the client must present to the server the 1396 clientid and an identifier for the owner of the requested lock. 1397 These two fields are referred to as the nfs_lockowner and the 1398 definition of those fields are: 1400 o A clientid returned by the server as part of the clients use of 1401 the SETCLIENTID procedure 1403 o A variable length opaque array used to uniquely define the owner 1404 of a lock managed by the client. 1406 This may be a thread id, process id, or other unique value. 1408 When the server grants the lock it responds with a unique 64-bit 1409 stateid. The stateid is used as a short hand reference to the 1410 nfs_lockowner, since the server will be maintaining the 1411 correspondence between them. 1413 7.2.3. Use of the stateid 1415 All I/O requests contain a stateid. If the nfs_lockowner performs 1416 I/O on a range of bytes within a locked range, the stateid returned 1417 by the server must be used to indicate the appropriate lock (record 1418 or share) is held. If no state is established by the client, either 1419 record lock or share lock, a stateid of all bits 0 is used. If no 1420 conflicting locks are held on the file, the server may grant the I/O 1421 request. If a conflict with an explicit lock occurs, the request is 1422 failed (NFS4ERR_LOCKED). This allows "mandatory locking" to be 1423 implemented. 1425 A stateid of all bits 1 allows read requests to bypass locking checks 1426 at the server. However, write requests with stateid with bits all 1 1427 does not bypass file locking requirements. 1429 An explicit lock may not be granted while an I/O operation with 1430 conflicting implicit locking is being performed. 1432 The byte range of a lock is indivisible. A range may be locked, 1433 unlocked, or changed between read and write but may not have 1434 subranges unlocked or changed between read and write. This is the 1435 semantics provided by Win32 but only a subset of the semantics 1436 provided by Unix. It is expected that Unix clients can more easily 1437 simulate modifying subranges than Win32 servers adding this feature. 1439 7.2.4. Sequencing of lock requests 1441 Locking is different than most NFS operations as it requires "at- 1442 most-one" semantics that are not provided by ONC RPC. In the face of 1443 retransmission or reordering, lock or unlock requests must have a 1444 well defined and consistent behavior. To accomplish this each lock 1445 request contains a sequence number that is a monotonically increasing 1446 integer. Different nfs_lockowners have different sequences. The 1447 server maintains the last sequence number (L) received and the 1448 response that was returned. If a request with a previous sequence 1449 number (r < L) is received it is silently ignored as its response 1450 must have been received before the last request (L) was sent. If a 1451 duplicate of last request (r == L) is received, the stored response 1452 is returned. If a request beyond the next sequence (r == L + 2) is 1453 received it is silently ignored. Sequences are reinitialized 1454 whenever the client verifier changes. 1456 7.3. Blocking locks 1458 Some clients require the support of blocking locks. The current 1459 proposal lacks a call-back mechanism, similar to NLM, to notify a 1460 client when the lock has been granted. Clients have no choice but to 1461 continually poll for the lock, which presents a fairness problem. 1462 Two new lock types are added, READW and WRITEW used to indicate to 1463 the server that the client is requesting a blocking lock. The server 1464 should maintain an ordered list of pending blocking locks. When the 1465 conflicting lock is released, the server may wait the lease period 1466 for the first client to re-request the lock. After the lease period 1467 expires the next waiting client request is allowed the lock. Clients 1468 are required to poll at an interval sufficiently small that it is 1469 likely to acquire the lock in a timely manner. The server is not 1470 required to maintain a list of pending blocked locks as it is used to 1471 increase fairness and not correct operation. Because of the 1472 unordered nature of crash recovery, storing of lock state to stable 1473 storage would be required to guarantee ordered granting of blocking 1474 locks. 1476 7.4. Lease renewal 1478 The purpose of a lease is to allow a server to remove stale locks 1479 that are held by a client that has crashed or is otherwise 1480 unreachable. It is not a mechanism for cache consistency and lease 1481 renewals may not be denied if the lease interval has not expired. 1482 Any I/O request that has been made with a valid stateid is a positive 1483 indication that the client is still alive and locks are being 1484 maintained. This becomes an implicit renewal of the lease. In the 1485 case no I/O has been performed within the lease interval, a lease can 1486 be renewed by having the client issue a zero length READ. Because 1487 the nfs_lockowner contains a unique client value, any stateid for a 1488 client will renew all leases for locks held with the same client 1489 field. This will allow very low overhead lease renewal that scales 1490 extremely well. In the typical case, no extra RPC calls are needed 1491 and in the worst case one RPC is required every lease period 1492 regardless of the number of locks held by the client. 1494 7.5. Crash recovery 1496 The important requirement in crash recovery is that both the client 1497 and the server know when the other has failed. Additionally it is 1498 required that a client sees a consistent view of data across server 1499 reboots. I/O operations that may have been queued within the client 1500 or network buffers, cannot complete until after the client has 1501 successfully recovered the lock protecting the I/O operation. 1503 If a client fails, the server only needs to wait the lease period to 1504 allow conflicting locks. If the client reinitializes within the 1505 lease period, it may be forced to wait the remainder of the period 1506 before resuming service. To minimize this delay, lock requests 1507 contain a verifier field in the lock_owner, if the server receives a 1508 verifier field that does not match the existing verifier, the server 1509 knows that the client has lost all lock state and locks held for that 1510 client that do not match the current verifier may be released. In a 1511 secure environment, a change in the verifier must only cause the 1512 locks held by the authenticated requester to be released in order to 1513 prevent a rogue user from freeing otherwise valid locks. The 1514 verifier must have the same uniqueness properties of the COMMIT 1515 verifier. 1517 If the server fails and loses locking state, the server must wait the 1518 lease period before granting any new locks or allowing any I/O. An 1519 I/O request during the grace period with an invalid stateid will fail 1520 with NFS4ERR_GRACE, the client will reissue the lock request with 1521 reclaim set to TRUE, and upon receiving a successful reply, the I/O 1522 may be reissued with the new stateid. Any time a client receives an 1523 NFS4ERR_GRACE error it should start recovering all outstanding locks. 1524 A lock request during the grace period without reclaim set will also 1525 result in a NFS4ERR_GRACE, triggering the client recovery processing. 1526 A lock request outside the grace period with reclaim set will succeed 1527 only if the server can guarantee that no conflicting lock or I/O 1528 request has been granted since reboot. 1530 In the case of a network partition longer than the lease period, the 1531 server will have not received an implicit lease renewal and may free 1532 all locks held for the client, thus invalidating any stateid held by 1533 the client. Subsequent reconnection will cause I/O with invalid 1534 stateid to fail with NFS4ERR_EXPIRED, the client will suitably notify 1535 the application holding the lock. After the lease period has expired 1536 the server may optionally continue to hold the locks for the client. 1537 In this case, if a conflicting lock or I/O request is received, the 1538 lock must be freed to allow the client to detect possible corruption. 1539 When there is a network partition and the lease expires, the server 1540 must record on stable storage the client information relating to 1541 those leases. This is to prevent the case where another client 1542 obtains the conflicting lock, frees the lock, and the server reboots. 1543 After the server recovers the original client may recover the network 1544 partition and attempt to reclaim the lock. Without any state to 1545 indicate that a conflicting may have occurred, the client could get 1546 in an inconsistent state. Storing just the client information is the 1547 minimal state necessary to detect this condition, but could lead to 1548 losing locks unnecessarily. However this is considered to be a very 1549 rare event, and a sophisticated server could store more state 1550 completely eliminate any unnecessary locks being lost. 1552 7.6. Server revocation of locks 1554 The server can revoke the locks held by a client at any time, when 1555 the client detects revocation it must ensure its state matches that 1556 of the server. If locks are revoked due to a server reboot, the 1557 client will receive a NFS4ERR_GRACE and normal crash recovery 1558 described above will be performed. 1560 The server may revoke a lock within the lease period, this is 1561 considered a rare event likely to be initiated only by a human (as 1562 part of an administration task). The client may assume that only the 1563 file that caused the NFS4ERR_EXPIRED to be returned has lost the 1564 lock_owner's locks and notifies the holder appropriately. The client 1565 can not assume the lease period has been renewed. 1567 The client not being able to renew the lease period is a relatively 1568 rare and unusual state. Both sides will detect this state and can 1569 recover without data corruption. The client must mark all locks held 1570 as "invalidated" and then must issue an I/O request, either a pending 1571 I/O or zero length read to revalidate the lock. If the response is 1572 success the lock is upgraded to valid, otherwise it was revoked by 1573 the server and the owner is notified. 1575 7.7. Share Reservations 1577 A share reservation is a mechanism to control access to a file. It 1578 is a separate and independent mechanism from record locking. When a 1579 client opens a file, it issues an OPEN request to the server 1580 specifying the type of access required (READ, WRITE, or BOTH) and the 1581 type of access to deny others (deny NONE, READ, WRITE, or BOTH). If 1582 the OPEN fails the client will fail the applications open request. 1584 Pseudo-code definition of the semantics: 1586 if ((request.access & file_state.deny)) || 1587 (request.deny & file_state.access)) 1588 return (NFS4ERR_DENIED) 1590 Old DOS applications specify shares in compatibility mode. Microsoft 1591 has indicated in the Win32 specification that it will be deprecated 1592 in the future and recommends that deny NONE be used. This 1593 specification does not support compatibility mode. 1595 7.8. OPEN/CLOSE procedures 1597 To provide correct share semantics, a client MUST use the OPEN 1598 procedure to obtain the initial file handle and indicate the desired 1599 access and what if any access to deny. Even if the client intends to 1600 use a stateid of all 0's or all 1's, it must still obtain the 1601 filehandle for the regular file with the OPEN procedure. For clients 1602 that do not have a deny mode built into their open API, deny equal to 1603 NONE should be used. 1605 The OPEN procedure with the CREATE flag, also subsumes the CREATE 1606 procedure for regular files as used in previous versions of NFS, 1607 allowing a create with a share to be done atomicly. 1609 Will expand on create semantics here. 1611 The CLOSE procedure removes all share locks held by the lock_owner on 1612 that file. If record locks are held they should be explicitly 1613 unlocked. Some servers may not support the CLOSE of a file that 1614 still has record locks held; if so, CLOSE will fail and return an 1615 error. 1617 The LOOKUP procedure is preserved and will return a file handle 1618 without establishing any lock state on the server. Without a valid 1619 stateid, the server will assume the client has the least access. For 1620 example, a file opened with deny READ/WRITE cannot be accessed using 1621 a file handle obtained through LOOKUP. 1623 8. Defined Error Numbers 1625 NFS error numbers are assigned to failed operations within a compound 1626 request. A compound request contains a number of NFS operations that 1627 have their results encoded in sequence in a compound reply. The 1628 results of successful operations will consist of an NFS4_OK status 1629 followed by the encoded results of the operation. If an NFS 1630 operation fails, an error status will be entered in the reply and the 1631 compound request will be terminated. 1633 A description of each defined error follows: 1635 NFS4_OK Indicates the operation completed successfully. 1637 NFS4ERR_PERM Not owner. The operation was not allowed 1638 because the caller is either not a privileged 1639 user (root) or not the owner of the target of 1640 the operation. 1642 NFS4ERR_NOENT No such file or directory. The file or 1643 directory name specified does not exist. 1645 NFS4ERR_IO I/O error. A hard error (for example, a disk 1646 error) occurred while processing the requested 1647 operation. 1649 NFS4ERR_NXIO I/O error. No such device or address. 1651 NFS4ERR_ACCES Permission denied. The caller does not have the 1652 correct permission to perform the requested 1653 operation. Contrast this with NFS4ERR_PERM, 1654 which restricts itself to owner or privileged 1655 user permission failures. 1657 NFS4ERR_EXIST File exists. The file specified already exists. 1659 NFS4ERR_XDEV Attempt to do a cross-device hard link. 1661 NFS4ERR_NODEV No such device. 1663 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 1664 directory in a directory operation. 1666 NFS4ERR_ISDIR Is a directory. The caller specified a 1667 directory in a non-directory operation. 1669 NFS4ERR_INVAL Invalid argument or unsupported argument for an 1670 operation. Two examples are attempting a 1671 READLINK on an object other than a symbolic 1672 link or attempting to SETATTR a time field on a 1673 server that does not support this operation. 1675 NFS4ERR_FBIG File too large. The operation would have caused 1676 a file to grow beyond the server's limit. 1678 NFS4ERR_NOSPC No space left on device. The operation would 1679 have caused the server's file system to exceed 1680 its limit. 1682 NFS4ERR_ROFS Read-only file system. A modifying operation 1683 was attempted on a read-only file system. 1685 NFS4ERR_MLINK Too many hard links. 1687 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 1689 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 1690 was not empty. 1692 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The 1693 user's resource limit on the server has been 1694 exceeded. 1696 NFS4ERR_STALE Invalid file handle. The file handle given in 1697 the arguments was invalid. The file referred to 1698 by that file handle no longer exists or access 1699 to it has been revoked. 1701 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 1702 internal consistency checks. 1704 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 1705 during a SETATTR operation. 1707 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 1709 NFS4ERR_NOTSUPP Operation is not supported. 1711 NFS4ERR_TOOSMALL Buffer or request is too small. 1713 NFS4ERR_SERVERFAULT An error occurred on the server which does not 1714 map to any of the legal NFS version 4 protocol 1715 error values. The client should translate this 1716 into an appropriate error. UNIX clients may 1717 choose to translate this to EIO. 1719 NFS4ERR_BADTYPE An attempt was made to create an object of a 1720 type not supported by the server. 1722 NFS4ERR_JUKEBOX The server initiated the request, but was not 1723 able to complete it in a timely fashion. The 1724 client should wait and then try the request 1725 with a new RPC transaction ID. For example, 1726 this error should be returned from a server 1727 that supports hierarchical storage and receives 1728 a request to process a file that has been 1729 migrated. In this case, the server should start 1730 the immigration process and respond to client 1731 with this error. 1733 NFS4ERR_SAME Returned if an NVERIFY operation shows that no 1734 attributes have changed. 1736 NFS4ERR_DENIED An attempt to lock a file is denied. Since 1737 this may be a temporary condition, the client 1738 is encouraged to retry the lock request (with 1739 exponential backoff of timeout) until the lock 1740 is accepted. 1742 NFS4ERR_EXPIRED A lease has expired that is being used in the 1743 current procedure. 1745 NFS4ERR_LOCKED A read or write operation was attempted on a 1746 locked file. 1748 NFS4ERR_GRACE The server is in its recovery or grace period 1749 which should match the lease period of the 1750 server. 1752 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 1753 expired at the server. The client should 1754 attempt to recover the new file handle by 1755 traversing the server's file system name space. 1756 The file handle may have expired because the 1757 server has restarted, the file system object 1758 has been removed, or the file handle has been 1759 flushed from the server's internal mappings. 1761 NOTE: This error definition will need to be crisp and match 1762 the section describing the volatile file handles. 1764 NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share 1765 reservation has failed because of a share 1766 conflict. 1768 NFS4ERR_SAME This error is returned by the NVERIFY operation 1769 to signify that the attributes compared were 1770 the same as provided in the client's request. 1772 NFS4ERR_WRONGSEC The security mechanism being used by the client 1773 for the procedure does not match the server's 1774 security policy. The client should change the 1775 security mechanism being used and retry the 1776 operation. 1778 NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a 1779 client id is already in use by another client. 1781 NFS4ERR_RESOURCE For the processing of the COMPOUND procedure, 1782 the server may exhaust available resources and 1783 can not continue processing procedures within 1784 the COMPOUND operation. This error will be 1785 returned from the server in those instances of 1786 resource exhaustion related to the processing 1787 of the COMPOUND procedure. 1789 9. NFS Version 4 Requests 1791 For the NFS program, version 4, there are two traditional RPC 1792 procedures: NULL and COMPOUND. All other procedures for NFS version 1793 4 are defined in normal XDR/RPC syntax and semantics except that 1794 these procedures are encapsulated within the COMPOUND request. This 1795 requires that the client combine one or more NFSv4 procedures into a 1796 single request. 1798 9.1. Compound Procedure 1800 These compound requests provide the opportunity for better 1801 performance on high latency networks. The client can avoid 1802 cumulative latency of multiple RPCs by combining multiple dependent 1803 operations into a single compound request. A compound op may provide 1804 for protocol simplification by allowing the client to combine basic 1805 procedures into a single request that is customized for the client's 1806 environment. 1808 The basics of the COMPOUND procedures construction is: 1810 +-----------+-----------+-----------+-- 1811 | op + args | op + args | op + args | 1812 +-----------+-----------+-----------+-- 1814 and the reply looks like this: 1816 +----------------+----------------+----------------+-- 1817 | code + results | code + results | code + results | 1818 +----------------+----------------+----------------+-- 1820 Where "code" is an indication of the success or failure of the 1821 operation including the opcode itself. 1823 9.2. Evaluation of a Compound Request 1825 The server will process the COMPOUND procedure by evaluating each of 1826 the procedures within the COMPOUND request in order. Each component 1827 procedure or operation consists of a 32 bit operation code, followed 1828 by the argument of length determined by the type of operation. The 1829 results of each operation are encoded in sequence into a reply 1830 buffer. The results of each operation are preceded by the opcode and 1831 a status code (normally zero). If an operation results in a non-zero 1832 status code, the status will be encoded and evaluation of the 1833 compound sequence will halt and the reply will be returned. 1835 There are no atomicity requirements for the procedures contained 1836 within the COMPOUND procedure. The procedures being evaluated as 1837 part of a COMPOUND request may and more than likely will be evaluated 1838 simultaneously with other COMPOUND requests that the server receives. 1840 It is the client's responsibility for recovering from any partially 1841 completed compound request. 1843 Each operation assumes a "current" filehandle that is available as 1844 part of the execution context of the compound request. Operations 1845 may set, change, or return this filehandle. 1847 10. NFS Version 4 Procedures 1849 10.1. Procedure 0: NULL - No Operation 1851 SYNOPSIS 1853 1855 ARGUMENT 1857 void; 1859 RESULT 1861 void; 1863 DESCRIPTION 1865 Standard ONCRPC NULL procedure. Void argument, void response. 1867 ERRORS 1869 None. 1871 10.2. Procedure 1: COMPOUND - Compound Operations 1873 SYNOPSIS 1875 compoundargs -> compoundres 1877 ARGUMENT 1879 union opunion switch (unsigned opcode) { 1880 case : ; 1881 ... 1882 }; 1884 struct op { 1885 opunion ops; 1886 }; 1888 struct COMPOUND4args { 1889 utf8string tag; 1890 op oplist<>; 1891 }; 1893 RESULT 1895 struct COMPOUND4resok { 1896 utf8string tag; 1897 resultdata data<>; 1898 }; 1900 union COMPOUND4res switch (nfsstat4 status){ 1901 case NFS4_OK: 1902 COMPOUND4resok resok4; 1903 default: 1904 void; 1905 }; 1907 DESCRIPTION 1909 The COMPOUND procedure is used to combine one or more of the NFS 1910 procedures into a single RPC request. The main NFS RPC program has 1911 two main procedures: NULL and COMPOUND. All other procedures use 1912 the COMPOUND procedure as a wrapper. 1914 In the processing of the COMPOUND procedure, the server may find 1915 that it does not have the available resources to execute any or all 1916 of the procedures within the COMPOUND sequence. In this case, the 1917 error NFS4ERR_RESOURCE will be returned for the particular 1918 procedure within the COMPOUND operation where the resource 1919 exhaustion occurred. This assume that all previous procedures 1920 within the COMPOUND sequence have been evaluated successfully. 1922 IMPLEMENTATION 1924 The COMPOUND procedure is used to combine individual procedures 1925 into a single RPC request. The server interprets each of the 1926 procedures in turn. If a procedure is executed by the server and 1927 the status of that procedure is NFS4_OK, then the next procedure in 1928 the COMPOUND procedure is executed. The server continues this 1929 process until there are no more procedures to be executed or one of 1930 the procedures has a status value other than NFS4_OK. 1932 ERRORS 1934 NFS4ERR_RESOURCE 1936 10.3. Procedure 2: ACCESS - Check Access Permission 1938 SYNOPSIS 1940 (cfh), permbits -> permbits 1942 ARGUMENT 1944 const ACCESS4_READ= 0x0001; 1945 const ACCESS4_LOOKUP= 0x0002; 1946 const ACCESS4_MODIFY= 0x0004; 1947 const ACCESS4_EXTEND= 0x0008; 1948 const ACCESS4_DELETE= 0x0010; 1949 const ACCESS4_EXECUTE= 0x0020; 1951 struct ACCESS4args { 1952 /* CURRENT_FH: object */ 1953 uint32_taccess; 1954 }; 1956 RESULT 1958 struct ACCESS4resok { 1959 uint32_taccess; 1960 }; 1962 union ACCESS4res switch (nfsstat4 status) { 1963 case NFS4_OK: 1964 ACCESS4resokresok; 1965 default: 1966 void; 1967 }; 1969 DESCRIPTION 1971 ACCESS determines the access rights that a user, as identified by 1972 the credentials in the request, has with respect to a file system 1973 object. The client encodes the set of permissions that are to be 1974 checked in a bit mask. The server checks the permissions encoded 1975 in the bit mask. A status of NFS4_OK is returned along with a bit 1976 mask encoded with the permissions that the client is allowed. 1978 The results of this procedure are necessarily advisory in nature. 1979 That is, a return status of NFS4_OK and the appropriate bit set in 1980 the bit mask does not imply that such access will be allowed to the 1981 file system object in the future, as access rights can be revoked 1982 by the server at any time. 1984 The following access permissions may be requested: 1986 ACCESS_READ: bit 1 Read data from file or read 1987 a directory. 1988 ACCESS_MODIFY: bit 2 Rewrite existing file data or modify 1989 existing directory entries. 1990 ACCESS_LOOKUP: bit 3 Look up a name in a 1991 directory (no meaning for 1992 non-directory objects). 1993 ACCESS_EXTEND: bit 4 Write new data or add 1994 directory entries. 1995 ACCESS_DELETE: bit 5 Delete an existing 1996 directory entry. 1997 ACCESS_EXECUTE: bit 6 Execute file (no meaning 1998 for a directory). 2000 The server must return an error if the any access permission cannot 2001 be determined. 2003 IMPLEMENTATION 2005 In general, it is not sufficient for the client to attempt to 2006 deduce access permissions by inspecting the uid, gid, and mode 2007 fields in the file attributes, since the server may perform uid or 2008 gid mapping or enforce additional access control restrictions. It 2009 is also possible that the NFS version 4 protocol server may not be 2010 in the same ID space as the NFS version 4 protocol client. In these 2011 cases (and perhaps others), the NFS version 4 protocol client can 2012 not reliably perform an access check with only current file 2013 attributes. 2015 In the NFS version 2 protocol, the only reliable way to determine 2016 whether an operation was allowed was to try it and see if it 2017 succeeded or failed. Using the ACCESS procedure in the NFS version 2018 4 protocol, the client can ask the server to indicate whether or 2019 not one or more classes of operations are permitted. The ACCESS 2020 operation is provided to allow clients to check before doing a 2021 series of operations. This is useful in operating systems (such as 2022 UNIX) where permission checking is done only when a directory is 2023 opened. This procedure is also invoked by NFS client access 2024 procedure (called possibly through access(2)). The intent is to 2025 make the behavior of opening a remote file more consistent with the 2026 behavior of opening a local file. 2028 For NFS version 4, the use of the ACCESS procedure when opening a 2029 regular file is deprecated in favor of using OPEN. 2031 The information returned by the server in response to an ACCESS 2032 call is not permanent. It was correct at the exact time that the 2033 server performed the checks, but not necessarily afterwards. The 2034 server can revoke access permission at any time. 2036 The NFS version 4 protocol client should use the effective 2037 credentials of the user to build the authentication information in 2038 the ACCESS request used to determine access rights. It is the 2039 effective user and group credentials that are used in subsequent 2040 read and write operations. 2042 Many implementations do not directly support the ACCESS_DELETE 2043 permission. Operating systems like UNIX will ignore the 2044 ACCESS_DELETE bit if set on an access request on a non-directory 2045 object. In these systems, delete permission on a file is determined 2046 by the access permissions on the directory in which the file 2047 resides, instead of being determined by the permissions of the file 2048 itself. Thus, the bit mask returned for such a request will have 2049 the ACCESS_DELETE bit set to 0, indicating that the client does not 2050 have this permission. 2052 ERRORS 2054 NFS4ERR_IO 2056 NFS4ERR_ACCES 2058 NFS4ERR_SERVERFAULT 2060 NFS4ERR_STALE 2062 NFS4ERR_BADHANDLE 2064 NFS4ERR_FHEXPIRED 2066 NFS4ERR_WRONGSEC 2068 10.4. Procedure 3: CLOSE - Close File 2070 SYNOPSIS 2072 (cfh), stateid -> stateid 2074 ARGUMENT 2076 struct CLOSE4args { 2077 stateid4stateid; 2078 }; 2080 RESULT 2082 union CLOSE4res switch (nfsstat4 status) { 2083 case NFS4_OK: 2084 stateid4stateid; 2085 default: 2086 void; 2087 }; 2089 DESCRIPTION 2091 The CLOSE procedure notifies the server that all share reservations 2092 corresponding to the client supplied stateid should be released. 2094 IMPLEMENTATION 2096 Share reservations for the matching stateid will be released on 2097 successful completion of the CLOSE procedure. 2099 ERRORS 2101 NFS4ERR_INVAL 2103 NFS4ERR_STALE 2105 NFS4ERR_BADHANDLE 2106 NFS4ERR_SERVERFAULT 2108 NFS4ERR_EXPIRED 2110 NFS4ERR_GRACE 2112 NFS4ERR_FHEXPIRED 2114 10.5. Procedure 4: COMMIT - Commit Cached Data 2116 SYNOPSIS 2118 (cfh), offset, count -> verifier 2120 ARGUMENT 2122 struct COMMIT4args { 2123 /* CURRENT_FH: file */ 2124 offset4offset; 2125 count4count; 2126 }; 2128 RESULT 2130 struct COMMIT4resok { 2131 writeverf4verf; 2132 }; 2134 union COMMIT4res switch (nfsstat4 status) { 2135 case NFS4_OK: 2136 COMMIT4resokresok4; 2137 default: 2138 void; 2139 }; 2141 DESCRIPTION 2143 The COMMIT procedure forces or flushes data to stable storage that 2144 was previously written with a WRITE operation which had the stable 2145 field set to UNSTABLE4. 2147 The offset provided by the client represents the position within 2148 the file at which the flush is to begin. An offset value of 0 2149 (zero) means to flush data starting at the beginning of the file. 2150 The count as provided by the client is the number of bytes of data 2151 to flush. If count is 0 (zero), a flush from offset to the end of 2152 file is done. 2154 The server returns a write verifier upon successful completion of 2155 the COMMIT. The write verifier is used by the client to determine 2156 if the server has restarted or rebooted between the initial 2157 WRITE(s) and the COMMIT. The client does this by comparing the 2158 write verifier returned from the initial writes and the verifier 2159 returned by the COMMIT procedure. The server must vary the value 2160 of the write verifier at each server event that may lead to a loss 2161 of uncommitted data. Most commonly this occurs when the server is 2162 rebooted; however, other events at the server may result in 2163 uncommitted data loss as well. 2165 IMPLEMENTATION 2167 The COMMIT procedure is similar in operation and semantics to the 2168 POSIX fsync(2) system call that synchronizes a file's state with 2169 the disk (file data and metadata is flushed to disk or stable 2170 storage). COMMIT performs the same operation for a client, flushing 2171 any unsynchronized data and metadata on the server to the server's 2172 disk or stable storage for the specified file. Like fsync(2), it 2173 may be that there is some modified data or no modified data to 2174 synchronize. The data may have been synchronized by the server's 2175 normal periodic buffer synchronization activity. COMMIT should 2176 return NFS4_OK, unless there has been an unexpected error. 2178 COMMIT differs from fsync(2) in that it is possible for the client 2179 to flush a range of the file (most likely triggered by a buffer- 2180 reclamation scheme on the client before file has been completely 2181 written). 2183 The server implementation of COMMIT is reasonably simple. If the 2184 server receives a full file COMMIT request, that is starting at 2185 offset 0 and count 0, it should do the equivalent of fsync()'ing 2186 the file. Otherwise, it should arrange to have the cached data in 2187 the range specified by offset and count to be flushed to stable 2188 storage. In both cases, any metadata associated with the file must 2189 be flushed to stable storage before returning. It is not an error 2190 for there to be nothing to flush on the server. This means that 2191 the data and metadata that needed to be flushed have already been 2192 flushed or lost during the last server failure. 2194 The client implementation of COMMIT is a little more complex. 2195 There are two reasons for wanting to commit a client buffer to 2196 stable storage. The first is that the client wants to reuse a 2197 buffer. In this case, the offset and count of the buffer are sent 2198 to the server in the COMMIT request. The server then flushes any 2199 cached data based on the offset and count, and flushes any metadata 2200 associated with the file. It then returns the status of the flush 2201 and the write verifier. The other reason for the client to 2202 generate a COMMIT is for a full file flush, such as may be done at 2203 close. In this case, the client would gather all of the buffers 2204 for this file that contain uncommitted data, do the COMMIT 2205 operation with an offset of 0 and count of 0, and then free all of 2206 those buffers. Any other dirty buffers would be sent to the server 2207 in the normal fashion. 2209 After a buffer is written by the client with stable parameter set 2210 to UNSTABLE, the buffer must be considered as modified by the 2211 client until the buffer has either been flushed via a COMMIT 2212 operation or written via a WRITE operation with stable parameter 2213 set to FILE_SYNC or DATA_SYNC. This is done to prevent the buffer 2214 from being freed and reused before the data can be flushed to 2215 stable storage on the server. 2217 When a response comes back from either a WRITE or a COMMIT 2218 operation and it contains a write verifier that is different than 2219 previously returned by the server, the client will need to 2220 retransmit all of the buffers containing uncommitted cached data to 2221 the server. How this is to be done is up to the implementor. If 2222 there is only one buffer of interest, then it should probably be 2223 sent back over in a WRITE request with the appropriate stable 2224 parameter. If there is more than one buffer, it might be worthwhile 2225 retransmitting all of the buffers in WRITE requests with the stable 2226 parameter set to UNSTABLE and then retransmitting the COMMIT 2227 operation to flush all of the data on the server to stable storage. 2228 The timing of these retransmissions is left to the implementor. 2230 The above description applies to page-cache-based systems as well 2231 as buffer-cache-based systems. In those systems, the virtual memory 2232 system will need to be modified instead of the buffer cache. 2234 ERRORS 2236 NFS4ERR_IO 2238 NFS4ERR_LOCKED 2240 NFS4ERR_SERVERFAULT 2242 10.6. Procedure 5: CREATE - Create a Non-Regular File Object 2244 SYNOPSIS 2246 (cfh), name, type, how -> (cfh) 2248 ARGUMENT 2250 struct CREATE4args { 2251 /* CURRENT_FH: directory for creation */ 2252 filename4objname; 2253 fattr4_typetype; 2254 createhow4createhow; 2255 }; 2257 RESULT 2259 struct CREATE4res { 2260 nfsstat4status; 2261 }; 2263 DESCRIPTION 2265 The CREATE procedure creates an non-regular file object in a 2266 directory with a given name. The OPEN procedure MUST be used to 2267 create a regular file. 2269 The need for exclusive create semantics for non-regular 2270 files needs to be decided upon and decisions about storage 2271 location of the verifier will need to be determined as 2272 well. 2274 The objtype determines the type of object to be created: directory, 2275 symlink, etc. The how union may have a value of UNCHECKED, GUARDED, 2276 and EXCLUSIVE. UNCHECKED means that the object should be created 2277 without checking for the existence of a duplicate object in the same 2278 directory. In this case, attrbits and attrvals describe the initial 2279 attributes for the file object. GUARDED specifies that the server 2280 should check for the presence of a duplicate object before performing 2281 the create and should fail the request with NFS4ERR_EXIST if a 2282 duplicate object exists. If the object does not exist, the request is 2283 performed as described for UNCHECKED. EXCLUSIVE specifies that the 2284 server is to follow exclusive creation semantics, using the verifier 2285 to ensure exclusive creation of the target. No attributes may be 2286 provided in this case, since the server may use the target object 2287 meta-data to store the verifier. 2289 The current filehandle is replaced by that of the new object. 2291 IMPLEMENTATION 2292 The CREATE procedure carries support for EXCLUSIVE create forward 2293 from NFS version 3. As in NFS version 3, this mechanism provides 2294 reliable exclusive creation. Exclusive create is invoked when the 2295 how parameter is EXCLUSIVE. In this case, the client provides a 2296 verifier that can reasonably be expected to be unique. A 2297 combination of a client identifier, perhaps the client network 2298 address, and a unique number generated by the client, perhaps the 2299 RPC transaction identifier, may be appropriate. 2301 If the object does not exist, the server creates the object and 2302 stores the verifier in stable storage. For file systems that do 2303 not provide a mechanism for the storage of arbitrary file 2304 attributes, the server may use one or more elements of the object 2305 meta-data to store the verifier. The verifier must be stored in 2306 stable storage to prevent erroneous failure on retransmission of 2307 the request. It is assumed that an exclusive create is being 2308 performed because exclusive semantics are critical to the 2309 application. Because of the expected usage, exclusive CREATE does 2310 not rely solely on the normally volatile duplicate request cache 2311 for storage of the verifier. The duplicate request cache in 2312 volatile storage does not survive a crash and may actually flush 2313 on a long network partition, opening failure windows. In the UNIX 2314 local file system environment, the expected storage location for 2315 the verifier on creation is the meta-data (time stamps) of the 2316 object. For this reason, an exclusive object create may not 2317 include initial attributes because the server would have nowhere 2318 to store the verifier. 2320 If the server can not support these exclusive create semantics, 2321 possibly because of the requirement to commit the verifier to 2322 stable storage, it should fail the CREATE request with the error, 2323 NFS4ERR_NOTSUPP. 2325 During an exclusive CREATE request, if the object already exists, 2326 the server reconstructs the object's verifier and compares it with 2327 the verifier in the request. If they match, the server treats the 2328 request as a success. The request is presumed to be a duplicate of 2329 an earlier, successful request for which the reply was lost and 2330 that the server duplicate request cache mechanism did not detect. 2332 If the verifiers do not match, the request is rejected with the 2333 status, NFS4ERR_EXIST. 2335 Once the client has performed a successful exclusive create, it 2336 must issue a SETATTR to set the correct object attributes. Until 2337 it does so, it should not rely upon any of the object attributes, 2338 since the server implementation may need to overload object meta- 2339 data to store the verifier. 2341 Use of the GUARDED attribute does not provide exactly-once 2342 semantics. In particular, if a reply is lost and the server does 2343 not detect the retransmission of the request, the procedure can 2344 fail with NFS4ERR_EXIST, even though the create was performed 2345 successfully. 2347 Note: 2349 1. Need to determine an initial set of attributes 2350 that must be set, and a set of attributes that 2351 can optionally be set, on a per-filetype basis. 2352 For instance, if the filetype is a NF4BLK then 2353 the device attributes must be set. 2355 2. Need to consider the symbolic link path as 2356 an "attribute". No need for a READLINK op 2357 if this is so. Similarly, a filehandle could 2358 be defined as an attribute for LINK. 2360 ERRORS 2362 NFS4ERR_IO 2364 NFS4ERR_ACCES 2366 NFS4ERR_EXIST 2368 NFS4ERR_NOTDIR 2370 NFS4ERR_INVAL 2372 NFS4ERR_NOSPC 2374 NFS4ERR_ROFS 2375 NFS4ERR_NAMETOOLONG 2377 NFS4ERR_DQUOT 2379 NFS4ERR_NOTSUPP 2381 NFS4ERR_SERVERFAULT 2383 NFS4ERR_FHEXPIRED 2385 NFS4ERR_WRONGSEC 2387 10.7. Procedure 6: GETATTR - Get Attributes 2389 SYNOPSIS 2391 (cfh), attrbits -> attrbits, attrvals 2393 ARGUMENT 2395 struct GETATTR4args { 2396 /* CURRENT_FH: directory or file */ 2397 bitmap4 attr_request; 2398 }; 2400 RESULT 2402 struct GETATTR4resok { 2403 fattr4 obj_attributes; 2404 }; 2406 union GETATTR4res switch (nfsstat4 status) { 2407 case NFS4_OK: 2408 GETATTR4resokresok4; 2409 default: 2410 void; 2411 }; 2413 DESCRIPTION 2415 The GETATTR procedure will obtain attributes from the server. The 2416 client sets a bit in the bitmap argument for each attribute value 2417 that it would like the server to return. The server returns an 2418 attribute bitmap that indicates the attribute values for which it 2419 was able to return, followed by the attribute values ordered lowest 2420 attribute number first. 2422 The server must return a value for each attribute that the client 2423 requests if the attribute is supported by the server. If the 2424 server does not support an attribute or cannot approximate a useful 2425 value then it must not return the attribute value and must not set 2426 the attribute bit in the result bitmap. The server must return an 2427 error if it supports an attribute but cannot obtain its value. In 2428 that case no attribute values will be returned. 2430 All servers must support attribute 0 (zero) which is a bitmap of 2431 all supported attributes for the filesystem object. 2433 IMPLEMENTATION 2435 ERRORS 2437 NFS4ERR_IO 2439 NFS4ERR_ACCES 2441 NFS4ERR_INVAL 2443 NFS4ERR_STALE 2445 NFS4ERR_BADHANDLE 2447 NFS4ERR_SERVERFAULT 2449 NFS4ERR_JUKEBOX 2451 NFS4ERR_FHEXPIRED 2453 10.8. Procedure 7: GETFH - Get Current Filehandle 2455 SYNOPSIS 2457 (cfh) -> filehandle 2459 ARGUMENT 2461 /* CURRENT_FH: */ 2462 void; 2464 RESULT 2466 struct GETFH4resok { 2467 nfs4_fh object; 2468 }; 2470 union GETFH4res switch (nfsstat4 status) { 2471 case NFS4_OK: 2472 GETFH4resokresok4; 2473 default: 2474 void; 2475 }; 2477 DESCRIPTION 2479 Returns the current filehandle. Operations that change the current 2480 filehandle like LOOKUP or CREATE to not automatically return the 2481 new filehandle as a result. For instance, if a client needs to 2482 lookup a directory entry and obtain its filehandle then the 2483 following request is needed. 2485 1: PUTFH (directory filehandle) 2486 2: LOOKUP (entry name) 2487 3: GETFH 2489 IMPLEMENTATION 2490 ERRORS 2492 NFS4ERR_SERVERFAULT 2494 10.9. Procedure 8: LINK - Create Link to a File 2496 SYNOPSIS 2498 (cfh), directory, newname -> (cfh) 2500 ARGUMENT 2502 struct LINK4args { 2503 /* CURRENT_FH: file */ 2504 nfs4_fh dir; 2505 filename4 newname; 2506 }; 2508 RESULT 2510 struct LINK4res { 2511 nfsstat4status; 2512 }; 2514 DESCRIPTION 2516 The LINK procedure creates an additional newname for the file with 2517 the current filehandle in the new directory dir file and link.dir 2518 must reside on the same file system and server. 2520 IMPLEMENTATION 2522 Changes to any property of the hard-linked files are reflected in 2523 all of the linked files. When a hard link is made to a file, the 2524 attributes for the file should have a value for nlink that is one 2525 greater than the value before the LINK. 2527 The comments under RENAME regarding object and target residing on 2528 the same file system apply here as well. The comments regarding the 2529 target name applies as well. 2531 ERRORS 2533 NFS4ERR_IO 2534 NFS4ERR_ACCES 2536 NFS4ERR_EXIST 2538 NFS4ERR_XDEV 2540 NFS4ERR_NOTDIR 2542 NFS4ERR_INVAL 2544 NFS4ERR_NOSPC 2546 NFS4ERR_ROFS 2548 NFS4ERR_MLINK 2550 NFS4ERR_NAMETOOLONG 2552 NFS4ERR_DQUOT 2554 NFS4ERR_STALE 2556 NFS4ERR_BADHANDLE 2558 NFS4ERR_NOTSUPP 2560 NFS4ERR_SERVERFAULT 2562 NFS4ERR_FHEXPIRED 2564 10.10. Procedure 9: LOCK - Create Lock 2566 SYNOPSIS 2568 (cfh) type, seqid, reclaim, owner, offset, length -> stateid, 2569 access 2571 ARGUMENT 2573 struct lockown { 2574 clientid4clientid; 2575 opaqueowner<>; 2576 }; 2578 union nfs_lockowner switch (stateid4 stateid) { 2579 case 0: 2580 lockownident; 2581 default: 2582 void; 2583 }; 2585 enum nfs4_lock_type { 2586 READ_LT = 1, 2587 WRITE_LT = 2, 2588 READW_LT = 3,/* blocking read */ 2589 WRITEW_LT = 4/* blocking write */ 2590 }; 2592 struct LOCK4args { 2593 /* CURRENT_FH: file */ 2594 nfs4_lock_typetype; 2595 seqid4seqid; 2596 boolreclaim; 2597 nfs_lockownerowner; 2598 offset4offset; 2599 length4length; 2600 }; 2602 RESULT 2604 struct lockres { 2605 stateid4stateid; 2606 int32_taccess; 2607 }; 2608 union LOCK4res switch (nfsstat4 status) { 2609 case NFS4_OK: 2610 lockresresult; 2611 default: 2612 void; 2613 }; 2615 DESCRIPTION 2617 The LOCK procedure requests a record lock for the byte range 2618 specified by the offset and length parameters. The lock type is 2619 also specified to be one of the nfs4_lock_types. If this is a 2620 reclaim request, the reclaim parameter will be TRUE; 2622 IMPLEMENTATION 2624 The File Locking section contains a full description of this and 2625 the other file locking procedures. 2627 ERRORS 2629 NFS4ERR_ACCES 2631 NFS4ERR_ISDIR 2633 NFS4ERR_INVAL 2635 NFS4ERR_STALE 2637 NFS4ERR_BADHANDLE 2639 NFS4ERR_SERVERFAULT 2641 NFS4ERR_GRACE 2643 NFS4ERR_FHEXPIRED 2645 10.11. Procedure 10: LOCKT - Test For Lock 2647 SYNOPSIS 2649 (cfh) type, seqid, reclaim, owner, offset, length -> {void, 2650 NFS4ERR_DENIED -> owner} 2652 ARGUMENT 2654 struct LOCK4args { 2655 /* CURRENT_FH: file */ 2656 nfs4_lock_typetype; 2657 seqid4seqid; 2658 boolreclaim; 2659 nfs_lockownerowner; 2660 offset4offset; 2661 length4length; 2662 }; 2664 RESULT 2666 union LOCKT4res switch (nfsstat4 status) { 2667 case NFS4ERR_DENIED: 2668 nfs_lockownerowner; 2669 case NFS4_OK: 2670 void; 2671 default: 2672 void; 2673 }; 2675 DESCRIPTION 2677 The LOCKT procedure tests the lock as specified in the argument. 2678 The owner of the lock is returned in the event it is currently 2679 being held; if no lock is held, nothing other than NFS4_OK is 2680 returned. 2682 IMPLEMENTATION 2684 The File Locking section contains a full description of this and 2685 the other file locking procedures. 2687 ERRORS 2689 NFS4ERR_ACCES 2691 NFS4ERR_ISDIR 2693 NFS4ERR_INVAL 2695 NFS4ERR_STALE 2697 NFS4ERR_BADHANDLE 2699 NFS4ERR_SERVERFAULT 2701 NFS4ERR_DENIED 2703 NFS4ERR_GRACE 2705 NFS4ERR_FHEXPIRED 2707 10.12. Procedure 11: LOCKU - Unlock File 2709 SYNOPSIS 2711 (cfh) type, seqid, reclaim, owner, offset, length -> stateid 2713 ARGUMENT 2715 struct LOCK4args { 2716 /* CURRENT_FH: file */ 2717 nfs4_lock_typetype; 2718 seqid4seqid; 2719 boolreclaim; 2720 nfs_lockownerowner; 2721 offset4offset; 2722 length4length; 2723 }; 2725 RESULT 2727 union LOCKU4res switch (nfsstat4 status) { 2728 caseNFS4_OK: 2729 stateid4stateid_ok; 2730 default: 2731 stateid4stateid_oth; 2732 }; 2734 DESCRIPTION 2736 The LOCKU procedure unlocks the record lock specified by the 2737 parameters. 2739 IMPLEMENTATION 2741 The File Locking section contains a full description of this and 2742 the other file locking procedures. 2744 ERRORS 2746 NFS4ERR_ACCES 2747 NFS4ERR_ISDIR 2749 NFS4ERR_INVAL 2751 NFS4ERR_STALE 2753 NFS4ERR_BADHANDLE 2755 NFS4ERR_SERVERFAULT 2757 NFS4ERR_GRACE 2759 NFS4ERR_FHEXPIRED 2761 10.13. Procedure 12: LOOKUP - Lookup Filename 2763 SYNOPSIS 2765 (cfh), filenames -> (cfh) 2767 ARGUMENT 2769 struct LOOKUP4args { 2770 /* CURRENT_FH: directory */ 2771 filename4 filenames<>; 2772 }; 2774 RESULT 2776 struct LOOKUP4res { 2777 /* CURRENT_FH: object */ 2778 nfsstat4status; 2779 }; 2781 DESCRIPTION 2783 The current filehandle is assumed to refer to a directory. LOOKUP 2784 evaluates the pathname contained in the array of names and obtains 2785 a new current filehandle from the final name. All but the final 2786 name in the list must be the names of directories. 2788 If the pathname cannot be evaluated either because a component 2789 doesn't exist or because the client doesn't have permission to 2790 evaluate a component of the path, then an error will be returned 2791 and the current filehandle will be unchanged. 2793 IMPLEMENTATION 2795 If the client prefers a partial evaluation of the path then a 2796 sequence of LOOKUP operations can be substituted e.g. 2798 1. PUTFH (directory filehandle) 2799 2. LOOKUP "pub" "foo" "bar" 2800 3. GETFH 2802 or 2804 1. PUTFH (directory filehandle) 2805 2. LOOKUP "pub" 2806 3. GETFH 2807 4. LOOKUP "foo" 2808 5. GETFH 2809 6. LOOKUP "bar" 2810 7. GETFH 2812 NFS version 4 servers depart from the semantics of previous NFS 2813 versions in allowing LOOKUP requests to cross mountpoints on the 2814 server. The client can detect a mountpoint crossing by comparing 2815 the fsid attribute of the directory with the fsid attribute of the 2816 directory looked up. If the fsids are different then the new 2817 directory is a server mountpoint. Unix clients that detect a 2818 mountpoint crossing will need to mount the server's filesystem. 2820 Servers that limit NFS access to "shares" or "exported" filesystems 2821 should provide a pseudo-filesystem into which the exported 2822 filesystems can be integrated, so that clients can browse the 2823 server's namespace. The clients view of a pseudo filesystem will 2824 be limited to paths that lead to exported filesystems. 2826 Note: previous versions of the protocol assigned special semantics 2827 to the names "." and "..". NFS version 4 assigns no special 2828 semantics to these names. The LOOKUPP operator must be used to 2829 lookup a parent directory. 2831 Note that this procedure does not follow symbolic links. The 2832 client is responsible for all parsing of filenames including 2833 filenames that are modified by symbolic links encountered during 2834 the lookup process. 2836 ERRORS 2838 NFS4ERR_NOENT 2840 NFS4ERR_IO 2842 NFS4ERR_ACCES 2844 NFS4ERR_NOTDIR 2846 NFS4ERR_INVAL 2848 NFS4ERR_NAMETOOLONG 2849 NFS4ERR_STALE 2851 NFS4ERR_SERVERFAULT 2853 NFS4ERR_FHEXPIRED 2855 10.14. Procedure 13: LOOKUPP - Lookup Parent Directory 2857 SYNOPSIS 2859 (cfh) -> (cfh) 2861 ARGUMENT 2863 /* CURRENT_FH: object */ 2864 void; 2866 RESULT 2868 struct LOOKUPP4res { 2869 /* CURRENT_FH: directory */ 2870 nfsstat4status; 2871 }; 2873 DESCRIPTION 2875 The current filehandle is assumed to refer to a directory. LOOKUPP 2876 assigns the filehandle for its parent directory to be the current 2877 filehandle. If there is no parent directory an ENOENT error must 2878 be returned. 2880 IMPLEMENTATION 2882 As for LOOKUP, LOOKUPP will also cross mountpoints. 2884 ERRORS 2886 NFS4ERR_NOENT 2888 NFS4ERR_IO 2890 NFS4ERR_ACCES 2892 NFS4ERR_INVAL 2894 NFS4ERR_STALE 2895 NFS4ERR_SERVERFAULT 2897 NFS4ERR_FHEXPIRED 2899 10.15. Procedure 14: NVERIFY - Verify Difference in Attributes 2901 SYNOPSIS 2903 (cfh), attrbits, attrvals -> - 2905 ARGUMENT 2907 struct NVERIFY4args { 2908 /* CURRENT_FH: object */ 2909 bitmap4 attr_request; 2910 fattr4 obj_attributes; 2911 }; 2913 RESULT 2915 struct NVERIFY4res { 2916 nfsstat4status; 2917 }; 2919 DESCRIPTION 2921 This operation is used to prefix a sequence of operations to be 2922 performed if one or more attributes have changed on some filesystem 2923 object. If all the attributes match then the error NFS4ERR_SAME 2924 must be returned. 2926 IMPLEMENTATION 2928 This operation is useful as a cache validation operator. If the 2929 object to which the attributes belong has changed then the 2930 following operations may obtain new data associated with that 2931 object. For instance, to check if a file has been changed and 2932 obtain new data if it has: 2934 1. PUTFH (public) 2935 2. LOOKUP "pub" "foo" "bar" 2936 3. NVERIFY attrbits attrs 2937 4. READ 0 32767 2939 ERRORS 2941 NFS4ERR_IO 2943 NFS4ERR_ACCES 2945 NFS4ERR_STALE 2947 NFS4ERR_BADHANDLE 2949 NFS4ERR_SERVERFAULT 2951 NFS4ERR_FHEXPIRED 2953 NFS4ERR_SAME 2955 10.16. Procedure 15: OPEN - Open a Regular File 2957 SYNOPSIS 2959 (cfh), file, openhow, owner, seqid, reclaim, access, deny -> (cfh), 2960 stateid, access 2962 ARGUMENT 2964 struct OPEN4args { 2965 open_nameorfh file; 2966 openflag openhow; 2967 nfs_lockowner owner; 2968 seqid4 seqid; 2969 bool reclaim; 2970 int32_t access; 2971 int32_t deny; 2972 }; 2974 union open_nameoffh switch (bool reclaim_fh) { 2975 case FALSE: 2976 /* CURRENT_FH: directory */ 2977 filename4 filenames<>; 2978 case TRUE: 2979 /* CURRENT_FH: file on reclaim */ 2980 void; 2981 }; 2983 enum createmode4 { 2984 UNCHECKED = 0, 2985 GUARDED = 1, 2986 EXCLUSIVE = 2 2987 }; 2989 union createhow4 switch (createmode4 mode) { 2990 case UNCHECKED: 2991 case GUARDED: 2992 fattr4 createattrs; 2993 case EXCLUSIVE: 2994 createverf4 verf; 2995 }; 2997 enum opentype4 { 2998 OPEN4_NOCREATE0, 2999 OPEN4_CREATE1 3000 }; 3001 union openflag switch (opentype4 opentype) { 3002 case OPEN4_CREATE: 3003 createhow4how; 3004 default: 3005 void; 3006 }; 3008 /* 3009 * Access and Deny constants for open argument 3010 */ 3011 const OPEN4_ACCESS_READ = 0x0001; 3012 const OPEN4_ACCESS_WRITE= 0x0002; 3013 const OPEN4_ACCESS_BOTH = 0x0003; 3015 const OPEN4_DENY_NONE = 0x0000; 3016 const OPEN4_DENY_READ = 0x0001; 3017 const OPEN4_DENY_WRITE = 0x0002; 3018 const OPEN4_DENY_BOTH = 0x0003; 3020 RESULT 3022 union OPEN4res switch (nfsstat4 status) { 3023 case NFS4_OK: 3024 /* CURRENT_FH: opened file */ 3025 LOCK4resresok; 3026 default: 3027 void; 3028 }; 3030 DESCRIPTION 3032 The OPEN procedure creates and/or opens a regular file in a 3033 directory with the provided name. If the file does not exist at 3034 the server and creation is desired, specification of the method of 3035 creation is provided by the openhow parameter. The client has the 3036 choice of three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE. 3038 UNCHECKED means that the file should be created without checking 3039 for the existence of a duplicate object in the same directory. For 3040 this type of create, createattrs specifies the initial set of 3041 attributes for the file (NOTE: need to define exactly which 3042 attributes should be set and if the file exists, should the 3043 attributes be modified if the file exists). If GUARDED is 3044 specified, the server checks for the presence of a duplicate object 3045 by name before performing the create. If a duplicate exists, an 3046 error of NFS4ERR_EXIST is returned as the status. If the object 3047 does not exist, the request is performed as described for 3048 UNCHECKED. 3050 EXCLUSIVE specifies that the server is to follow exclusive creation 3051 semantics, using the verifier to ensure exclusive creation of the 3052 target. The server should check for the presence of a duplicate 3053 object by name. If the object does not exist, the server creates 3054 the object and stores the verifier with the object. If the object 3055 does exist and the stored verifier matches the client provided 3056 verifier, the server uses the existing object as the newly created 3057 object. If the stored verifier does not match, then an error of 3058 NFS4ERR_EXIST is returned. No attributes may be provided in this 3059 case, since the server may use an attribute of the target object to 3060 store the verifier. (NOTE: does a specific attribute need to be 3061 specified for storage of verifier ) 3063 Upon successful creation, the current filehandle is replaced by 3064 that of the new object. 3066 The OPEN procedure provides for DOS SHARE capability with the use 3067 of the access and deny fields of the OPEN arguments. The client 3068 specifies at OPEN the required access and deny modes. For clients 3069 that do not directly support SHAREs (i.e. Unix), the expected deny 3070 value is DENY_NONE. In the case that there is a existing SHARE 3071 reservation that conflicts with the OPEN request, the server 3072 returns the error NFS4ERR_DENIED. For a complete SHARE request, 3073 the client must provide values for the owner and seqid fields for 3074 the OPEN argument. For additional discussion of SHARE semantics 3075 see the section on 'Share Reservations'. 3077 In the case that the client is recovering state from a server 3078 failure, the reclaim field of the OPEN argument is use to signify 3079 that the request is meant to reclaim state previously held. 3081 The file field of the OPEN argument allows the client to specify an 3082 open by name or by filehandle. The filehandle MAY only be 3083 specified in the case that the OPEN is a reclaim request. It is 3084 expected that if the server is providing persistent filehandles, 3085 the client will not have file names saved to request a reclaim OPEN 3086 by name. 3088 For non-reclaim OPEN requests that reach the server during its 3089 grace or lease expiration period, the server returns an error of 3090 NFS4ERR_GRACE. 3092 IMPLEMENTATION 3094 The OPEN procedure contains support for EXCLUSIVE create. The 3095 mechanism is similar to the support in NFS version 3 [RFC1813]. As 3096 in NFS version 3, this mechanism provides reliable exclusive 3097 creation. Exclusive create is invoked when the how parameter is 3098 EXCLUSIVE. In this case, the client provides a verifier that can 3099 reasonably be expected to be unique. A combination of a client 3100 identifier, perhaps the client network address, and a unique number 3101 generated by the client, perhaps the RPC transaction identifier, 3102 may be appropriate. 3104 If the object does not exist, the server creates the object and 3105 stores the verifier in stable storage. For file systems that do not 3106 provide a mechanism for the storage of arbitrary file attributes, 3107 the server may use one or more elements of the object meta-data to 3108 store the verifier. The verifier must be stored in stable storage 3109 to prevent erroneous failure on retransmission of the request. It 3110 is assumed that an exclusive create is being performed because 3111 exclusive semantics are critical to the application. Because of the 3112 expected usage, exclusive CREATE does not rely solely on the 3113 normally volatile duplicate request cache for storage of the 3114 verifier. The duplicate request cache in volatile storage does not 3115 survive a crash and may actually flush on a long network partition, 3116 opening failure windows. In the UNIX local file system 3117 environment, the expected storage location for the verifier on 3118 creation is the meta-data (time stamps) of the object. For this 3119 reason, an exclusive object create may not include initial 3120 attributes because the server would have nowhere to store the 3121 verifier. 3123 If the server can not support these exclusive create semantics, 3124 possibly because of the requirement to commit the verifier to 3125 stable storage, it should fail the OPEN request with the error, 3126 NFS4ERR_NOTSUPP. 3128 During an exclusive CREATE request, if the object already exists, 3129 the server reconstructs the object's verifier and compares it with 3130 the verifier in the request. If they match, the server treats the 3131 request as a success. The request is presumed to be a duplicate of 3132 an earlier, successful request for which the reply was lost and 3133 that the server duplicate request cache mechanism did not detect. 3134 If the verifiers do not match, the request is rejected with the 3135 status, NFS4ERR_EXIST. 3137 Once the client has performed a successful exclusive create, it 3138 must issue a SETATTR to set the correct object attributes. Until 3139 it does so, it should not rely upon any of the object attributes, 3140 since the server implementation may need to overload object meta- 3141 data to store the verifier. The subsequent SETATTR must not occur 3142 in the same COMPOUND request as the OPEN. This separation will 3143 guarantee that the exclusive create mechanism will continue to 3144 function properly in the face of retransmission of the request. 3146 Use of the GUARDED attribute does not provide exactly-once 3147 semantics. In particular, if a reply is lost and the server does 3148 not detect the retransmission of the request, the procedure can 3149 fail with NFS4ERR_EXIST, even though the create was performed 3150 successfully. 3152 For SHARE reservations, the client must specify a value for access 3153 that is one of READ, WRITE, or BOTH. For deny, the client must 3154 specify one of NONE, READ, WRITE, or BOTH. If the client fails to 3155 do this, the server must return NFS4ERR_INVAL. 3157 ERRORS 3159 NFS4ERR_IO 3161 NFS4ERR_ACCES 3163 NFS4ERR_EXIST 3165 NFS4ERR_NOTDIR 3167 NFS4ERR_NOSPC 3169 NFS4ERR_ROFS 3171 NFS4ERR_NAMETOOLONG 3173 NFS4ERR_DQUOT 3175 NFS4ERR_NOTSUPP 3177 NFS4ERR_SERVERFAULT 3179 NFS4ERR_SHARE_DENIED 3181 NFS4ERR_GRACE 3183 10.17. Procedure 16: OPENATTR - Open Named Attribute Directory 3185 SYNOPSIS 3187 (cfh) -> (cfh) 3189 ARGUMENT 3191 /* CURRENT_FH: file or directory */ 3192 void; 3194 RESULT 3196 struct OPENATTR4res { 3197 /* CURRENT_FH: name attr directory*/ 3198 nfsstat4status; 3199 }; 3201 DESCRIPTION 3203 The OPENATTR procedure is used to obtain the filehandle of the 3204 named attribute directory associated with the current filehandle. 3205 The result of the OPENATTR will be a filehandle of type NF4ATTRDIR. 3206 From this filehandle, READDIR and LOOKUP procedures can be used to 3207 obtain filehandles for the various named attributes associated with 3208 the original file system object. Filehandles returned within the 3209 named attribute directory will have a type of NF4NAMEDATTR. 3211 IMPLEMENTATION 3213 If the server does not support named attributes for the current 3214 filehandle, an error of NFS4ERR_NOTSUPP will be returned to the 3215 client. 3217 ERRORS 3219 NFS4ERR_NOENT 3221 NFS4ERR_IO 3222 NFS4ERR_ACCES 3224 NFS4ERR_INVAL 3226 NFS4ERR_STALE 3228 NFS4ERR_BADHANDLE 3230 NFS4ERR_NOTSUPP 3232 NFS4ERR_SERVERFAULT 3234 NFS4ERR_JUKEBOX 3236 NFS4ERR_FHEXPIRED 3238 NFS4ERR_WRONGSEC 3240 10.18. Procedure 17: PUTFH - Set Current Filehandle 3242 SYNOPSIS 3244 filehandle -> (cfh) 3246 ARGUMENT 3248 struct PUTFH4args { 3249 nfs4_fh object; 3250 }; 3252 RESULT 3254 struct PUTFH4res { 3255 /* CURRENT_FH: */ 3256 nfsstat4status; 3257 }; 3259 DESCRIPTION 3261 Replaces the current filehandle with the filehandle provided as an 3262 argument. 3264 IMPLEMENTATION 3266 Commonly used as the first operator in any NFS request to set the 3267 context for following operations. 3269 ERRORS 3271 NFS4ERR_SERVERFAULT 3273 NFS4ERR_WRONGSEC 3275 10.19. Procedure 18: PUTPUBFH - Set Public Filehandle 3277 SYNOPSIS 3279 - -> (cfh) 3281 ARGUMENT 3283 void; 3285 RESULT 3287 struct PUTPUBFH4res { 3288 /* CURRENT_FH: root fh */ 3289 nfsstat4status; 3290 }; 3292 DESCRIPTION 3294 Replaces the current filehandle with the filehandle that represents 3295 the public filehandle of the server's namespace. This filehandle 3296 may be different from the "root" filehandle which may be associated 3297 with some other directory on the server. 3299 IMPLEMENTATION 3301 Used as the first operator in any NFS request to set the context 3302 for following operations. 3304 ERRORS 3306 NFS4ERR_SERVERFAULT NFS4ERR_WRONGSEC 3308 10.20. Procedure 19: PUTROOTFH - Set Root Filehandle 3310 SYNOPSIS 3312 - -> (cfh) 3314 ARGUMENT 3316 void; 3318 RESULT 3320 struct PUTROOTFH4res { 3321 /* CURRENT_FH: root fh */ 3322 nfsstat4status; 3323 }; 3325 DESCRIPTION 3327 Replaces the current filehandle with the filehandle that represents 3328 the root of the server's namespace. From this filehandle a LOOKUP 3329 operation can locate any other filehandle on the server. This 3330 filehandle may be different from the "public" filehandle which may 3331 be associated with some other directory on the server. 3333 IMPLEMENTATION 3335 Commonly used as the first operator in any NFS request to set the 3336 context for following operations. 3338 ERRORS 3340 NFS4ERR_SERVERFAULT 3342 NFS4ERR_WRONTSEC 3344 10.21. Procedure 20: READ - Read from File 3346 SYNOPSIS 3348 (cfh), offset, count, stateid -> eof, data 3350 ARGUMENT 3352 struct READ4args { 3353 /* CURRENT_FH: file */ 3354 stateid4stateid; 3355 offset4offset; 3356 count4count; 3357 }; 3359 RESULT 3361 struct READ4resok { 3362 booleof; 3363 opaquedata<>; 3364 }; 3366 union READ4res switch (nfsstat4 status) { 3367 case NFS4_OK: 3368 READ4resokresok4; 3369 default: 3370 void; 3371 }; 3373 DESCRIPTION 3375 The READ procedure reads data from the regular file identified by 3376 the current filehandle. 3378 The client provides an offset of where the READ is to start and a 3379 count of how many bytes are to be read. An offset of 0 (zero) 3380 means to read data starting at the beginning of the file. If offset 3381 is greater than or equal to the size of the file, the status, 3382 NFS4_OK, is returned with a data length set to 0 (zero) and eof set 3383 to TRUE. The READ is subject to access permissions checking. 3385 If the client specifies a count value of 0 (zero), the READ 3386 succeeds and returns 0 (zero) bytes of data again subject to access 3387 permissions checking. The server may choose to return fewer bytes 3388 than specified by the client. The client needs to check for this 3389 condition and handle the condition appropriately. 3391 The stateid value for a READ request represents a value returned 3392 from a previous record lock or share reservation request. Used by 3393 the server to verify that the associated lock is still valid and to 3394 update lease timeouts for the client. 3396 If the read ended at the end-of-file (formally, in a correctly 3397 formed READ request, if offset + count is equal to the size of the 3398 file), eof is returned as TRUE; otherwise it is FALSE. A successful 3399 READ of an empty file will always return eof as TRUE. 3401 IMPLEMENTATION 3403 It is possible for the server to return fewer than count bytes of 3404 data. If the server returns less than the count requested and eof 3405 set to FALSE, the client should issue another READ to get the 3406 remaining data. A server may return less data than requested under 3407 several circumstances. The file may have been truncated by another 3408 client or perhaps on the server itself, changing the file size from 3409 what the requesting client believes to be the case. This would 3410 reduce the actual amount of data available to the client. It is 3411 possible that the server may back off the transfer size and reduce 3412 the read request return. Server resource exhaustion may also occur 3413 necessitating a smaller read return. 3415 If the file is locked the server will return an NFS4ERR_LOCKED 3416 error. Since the lock may be of short duration, the client may 3417 choose to retransmit the READ request (with exponential backoff) 3418 until the operation succeeds. 3420 ERRORS 3422 NFS4ERR_IO 3424 NFS4ERR_NXIO 3426 NFS4ERR_ACCES 3428 NFS4ERR_INVAL 3430 NFS4ERR_STALE 3431 NFS4ERR_BADHANDLE 3433 NFS4ERR_SERVERFAULT 3435 NFS4ERR_DENIED 3437 NFS4ERR_JUKEBOX 3439 NFS4ERR_EXPIRED 3441 NFS4ERR_LOCKED 3443 NFS4ERR_GRACE 3445 NFS4ERR_FHEXPIRED 3447 NFS4ERR_WRONGSEC 3449 10.22. Procedure 21: READDIR - Read Directory 3451 SYNOPSIS 3452 (cfh), cookie, dircount, maxcount, attrbits -> { cookie, filename, 3453 attrbits, attributes } 3455 ARGUMENT 3457 struct READDIR4args { 3458 /* CURRENT_FH: directory */ 3459 nfs_cookie4cookie; 3460 count4dircount; 3461 count4maxcount; 3462 bitmap4attr_request; 3464 }; 3466 RESULT 3468 struct entry4 { 3469 nfs_cookie4cookie; 3470 filename4name; 3471 fattr4attrs; 3472 entry4*nextentry; 3473 }; 3475 struct dirlist4 { 3476 entry4*entries; 3477 booleof; 3478 }; 3480 struct READDIR4resok { 3481 dirlist4reply; 3482 }; 3484 union READDIR4res switch (nfsstat4 status) { 3485 case NFS4_OK: 3486 READDIR4resokresok4; 3487 default: 3488 void; 3489 }; 3491 DESCRIPTION 3493 The READDIR procedure retrieves a variable number of entries from a 3494 file system directory and returns complete information about each 3495 entry along with information to allow the client to request 3496 additional directory entries in a subsequent READDIR. 3498 The arguments contain a cookie value that represents where the 3499 READDIR should start within the directory. A value of 0 (zero) for 3500 the cookie is used to start reading at the beginning of the 3501 directory. For subsequent READDIR requests, the client specifies a 3502 cookie value that is provided by the server on a previous READDIR 3503 request. 3505 The dircount portion of the argument is the maximum number of bytes 3506 of directory information that should be returned. This value does 3507 not include the size of attributes or filehandle values that may be 3508 returned in the result. 3510 The maxcount value of the argument specifies the maximum number of 3511 bytes for the result. This maximum size represents all of the data 3512 being returned and includes the XDR overhead. The server may 3513 return less data. 3515 Finally, attrbits represents the list of attributes the client 3516 wants returned for each directory entry supplied by the server. 3518 On successful return, the server's response will provide a list of 3519 directory entries. Each of these entries contains the name of the 3520 directory entry, a cookie value for that entry and the associated 3521 attributes as requested. The cookie value is only meaningful to 3522 the server and is used as a "bookmark" for the directory entry. As 3523 mentioned, this cookie is used by the client for subsequent READDIR 3524 operations so that it may continue reading a directory. The cookie 3525 is similar in concept to a READ offset but should not be 3526 interpreted as such by the client. Ideally, the cookie value 3527 should not change if the directory is modified. 3529 IMPLEMENTATION 3531 Issues that need to be understood for this procedure include 3532 increased cache flushing activity on the client (as new file 3533 handles are returned with names which are entered into caches) and 3534 over-the-wire overhead versus expected subsequent LOOKUP and 3535 GETATTR elimination. 3537 The dircount and maxcount fields are included as an optimization. 3539 Consider a READDIR call on a UNIX operating system implementation 3540 for 1048 bytes; the reply does not contain many entries because of 3541 the overhead due to attributes and file handles. An alternative is 3542 to issue a READDIR call for 8192 bytes and then only use the first 3543 1048 bytes of directory information. However, the server doesn't 3544 know that all that is needed is 1048 bytes of directory information 3545 (as would be returned by READDIR). It sees the 8192 byte request 3546 and issues a VOP_READDIR for 8192 bytes. It then steps through all 3547 of those directory entries, obtaining attributes and file handles 3548 for each entry. When it encodes the result, the server only 3549 encodes until it gets 8192 bytes of results which include the 3550 attributes and file handles. Thus, it has done a larger VOP_READDIR 3551 and many more attribute fetches than it needed to. The ratio of the 3552 directory entry size to the size of the attributes plus the size of 3553 the file handle is usually at least 8 to 1. The server has done 3554 much more work than it needed to. 3556 The solution to this problem is for the client to provide two 3557 counts to the server. The first is the number of bytes of directory 3558 information that the client really wants, dircount. The second is 3559 the maximum number of bytes in the result, including the attributes 3560 and file handles, maxcount. Thus, the server will issue a 3561 VOP_READDIR for only the number of bytes that the client really 3562 wants to get, not an inflated number. This should help to reduce 3563 the size of VOP_READDIR requests on the server, thus reducing the 3564 amount of work done there, and to reduce the number of VOP_LOOKUP, 3565 VOP_GETATTR, and other calls done by the server to construct 3566 attributes and file handles. 3568 ERRORS 3570 NFS4ERR_IO 3572 NFS4ERR_ACCES 3574 NFS4ERR_NOTDIR 3576 NFS4ERR_INVAL 3578 NFS4ERR_STALE 3580 NFS4ERR_BADHANDLE 3582 NFS4ERR_BAD_COOKIE 3584 NFS4ERR_TOOSMALL 3585 NFS4ERR_NOTSUPP 3587 NFS4ERR_SERVERFAULT 3589 NFS4ERR_JUKEBOX 3591 NFS4ERR_FHEXPIRED 3593 NFS4ERR_WRONGSEC 3595 10.23. Procedure 22: READLINK - Read Symbolic Link 3597 SYNOPSIS 3599 (cfh) -> linktext 3601 ARGUMENT 3603 /* CURRENT_FH: symlink */ 3604 void; 3606 RESULT 3608 struct READLINK4resok { 3609 linktext4link; 3610 }; 3612 union READLINK4res switch (nfsstat4 status) { 3613 case NFS4_OK: 3614 READLINK4resokresok4; 3615 default: 3616 void; 3617 }; 3619 DESCRIPTION 3621 READLINK reads the data associated with a symbolic link. The data 3622 is a UTF-8 string that is opaque to the server. That is, whether 3623 created by an NFS client or created locally on the server, the data 3624 in a symbolic link is not interpreted when created, but is simply 3625 stored. 3627 IMPLEMENTATION 3629 A symbolic link is nominally a pointer to another file. The data 3630 is not necessarily interpreted by the server, just stored in the 3631 file. It is possible for a client implementation to store a path 3632 name that is not meaningful to the server operating system in a 3633 symbolic link. A READLINK operation returns the data to the client 3634 for interpretation. If different implementations want to share 3635 access to symbolic links, then they must agree on the 3636 interpretation of the data in the symbolic link. 3638 The READLINK operation is only allowed on objects of type, NF4LNK. 3639 The server should return the error, NFS4ERR_INVAL, if the object is 3640 not of type, NF4LNK. 3642 ERRORS 3644 NFS4ERR_IO 3646 NFS4ERR_INVAL 3648 NFS4ERR_ACCES 3650 NFS4ERR_STALE 3652 NFS4ERR_BADHANDLE 3654 NFS4ERR_NOTSUPP 3656 NFS4ERR_SERVERFAULT 3658 NFS4ERR_JUKEBOX 3660 NFS4ERR_FHEXPIRED 3662 NFS4ERR_WRONGSEC 3664 10.24. Procedure 23: REMOVE - Remove Filesystem Object 3666 SYNOPSIS 3668 (cfh), filename -> - 3670 ARGUMENT 3672 struct REMOVE4args { 3673 /* CURRENT_FH: directory */ 3674 filename4target; 3675 }; 3677 RESULT 3679 struct REMOVE4res { 3680 nfsstat4status; 3681 }; 3683 DESCRIPTION 3685 The REMOVE procecure removes (deletes) a directory entry named by 3686 filename from the directory corresponding to the current 3687 filehandle. If the entry in the directory was the last reference 3688 to the corresponding file system object, the object may be 3689 destroyed. 3691 IMPLEMENTATION 3693 NFS versions 2 and 3 required a different operator RMDIR for 3694 directory removal. NFS version 4 REMOVE can be used to delete any 3695 directory entry independent of its filetype. 3697 The concept of last reference is server specific. However, if the 3698 nlink field in the previous attributes of the object had the value 3699 1, the client should not rely on referring to the object via a file 3700 handle. Likewise, the client should not rely on the resources (disk 3701 space, directory entry, and so on.) formerly associated with the 3702 object becoming immediately available. Thus, if a client needs to 3703 be able to continue to access a file after using REMOVE to remove 3704 it, the client should take steps to make sure that the file will 3705 still be accessible. The usual mechanism used is to use RENAME to 3706 rename the file from its old name to a new hidden name. 3708 ERRORS 3710 NFS4ERR_NOENT 3712 NFS4ERR_IO 3714 NFS4ERR_ACCES 3716 NFS4ERR_NOTDIR 3718 NFS4ERR_ROFS 3720 NFS4ERR_NAMETOOLONG 3722 NFS4ERR_NOTEMPTY 3724 NFS4ERR_STALE 3726 NFS4ERR_BADHANDLE 3728 NFS4ERR_NOTSUPP 3730 NFS4ERR_SERVERFAULT 3732 NFS4ERR_FHEXPIRED 3734 NFS4ERR_WRONGSEC 3736 10.25. Procedure 24: RENAME - Rename Directory Entry 3738 SYNOPSIS 3740 (cfh), oldname, newdir, newname -> - 3742 ARGUMENT 3744 struct RENAME4args { 3745 /* CURRENT_FH: source directory */ 3746 filename4oldname; 3747 nfs4_fhnewdir; 3748 filename4newname; 3749 }; 3751 RESULT 3753 struct RENAME4res { 3754 nfsstat4status; 3755 }; 3757 DESCRIPTION 3759 RENAME renames the object identified by oldname in the directory 3760 corresponding to the current filehandle to newname in directory 3761 newdir. The operation is required to be atomic to the client. 3762 Source and target directories must reside on the same file system 3763 on the server. 3765 If the directory, newdir, already contains an entry with the name, 3766 newname, the source object must be compatible with the target: 3767 either both are non-directories or both are directories and the 3768 target must be empty. If compatible, the existing target is removed 3769 before the rename occurs. If they are not compatible or if the 3770 target is a directory but not empty, the server should return the 3771 error, NFS4ERR_EXIST. 3773 IMPLEMENTATION 3775 The RENAME operation must be atomic to the client. The statement 3776 "source and target directories must reside on the same file system 3777 on the server" means that the fsid fields in the attributes for the 3778 directories are the same. If they reside on different file systems, 3779 the error, NFS4ERR_XDEV, is returned. Even though the operation is 3780 atomic, the status, NFS4ERR_MLINK, may be returned if the server 3781 used a "unlink/link/unlink" sequence internally. 3783 A file handle may or may not become stale on a rename. However, 3784 server implementors are strongly encouraged to attempt to keep file 3785 handles from becoming stale in this fashion. 3787 On some servers, the filenames, "." and "..", are illegal as either 3788 oldname or newname. In addition, neither oldname nor newname can be 3789 an alias for the source directory. These servers will return the 3790 error, NFS4ERR_INVAL, in these cases. 3792 If oldname and newname both refer to the same file (they might be 3793 hard links of each other), then RENAME should perform no action and 3794 return success. 3796 ERRORS 3798 NFS4ERR_NOENT 3800 NFS4ERR_IO 3802 NFS4ERR_ACCES 3804 NFS4ERR_EXIST 3806 NFS4ERR_XDEV 3808 NFS4ERR_NOTDIR 3810 NFS4ERR_ISDIR 3812 NFS4ERR_INVAL 3814 NFS4ERR_NOSPC 3816 NFS4ERR_ROFS 3818 NFS4ERR_MLINK 3820 NFS4ERR_NAMETOOLONG 3822 NFS4ERR_NOTEMPTY 3823 NFS4ERR_DQUOT 3825 NFS4ERR_STALE 3827 NFS4ERR_BADHANDLE 3829 NFS4ERR_NOTSUPP 3831 NFS4ERR_SERVERFAULT 3833 NFS4ERR_FHEXPIRED 3835 NFS4ERR_WRONGSEC 3837 10.26. Procedure 25: RENEW - Renew a Lease 3839 SYNOPSIS 3841 stateid -> () 3843 ARGUMENT 3845 struct RENEW4args { 3846 stateid4stateid; 3847 }; 3849 RESULT 3851 struct RENEW4res { 3852 nfsstat4status; 3853 }; 3855 DESCRIPTION 3857 The RENEW procedure is used by the client to renew leases which it 3858 currently holds at a server. The processing the RENEW request, the 3859 server renews all leases associated with the client. The 3860 associated leases are determined by the client id provided via the 3861 SETCLIENTID procedure. 3863 IMPLEMENTATION 3865 ERRORS 3867 NFS4ERR_SERVERFAULT 3869 NFS4ERR_EXPIRED 3871 NFS4ERR_GRACE 3873 NFS4ERR_WRONGSEC 3875 10.27. Procedure 25: RESTOREFH - Restore Saved Filehandle 3877 SYNOPSIS 3879 (sfh) -> (cfh) 3881 ARGUMENT 3883 /* SAVED_FH: */ 3884 void; 3886 RESULT 3888 struct RESTOREFH4res { 3889 /* CURRENT_FH: value of saved fh */ 3890 nfsstat4status; 3891 }; 3893 DESCRIPTION 3895 Set the current filehandle to the value in the saved filehandle. 3896 If there is no saved filehandle then return an error NFS4ERR_INVAL. 3898 IMPLEMENTATION 3900 Procedures like OPEN and LOOKUP use the current filehandle to 3901 represent a directory and replace it with a new filehandle. 3902 Assuming the previous filehandle was saved with a SAVEFH operator, 3903 the previous filehandle can be restored as the current filehandle. 3904 This is commonly used to obtain post-operation attributes for the 3905 directory, e.g. 3907 1. PUTFH (directory filehandle) 3908 2. SAVEFH 3909 3. GETATTR attrbits (pre-op dir attrs) 3910 4. CREATE optbits "foo" attrs 3911 5. GETATTR attrbits (file attributes) 3912 6. RESTOREFH 3913 7. GETATTR attrbits (post-op dir attrs) 3915 ERRORS 3917 NFS4ERR_INVAL 3919 NFS4ERR_STALE 3921 NFS4ERR_BADHANDLE 3923 NFS4ERR_SERVERFAULT 3925 NFS4ERR_FHEXPIRED 3927 NFS4ERR_WRONGSEC 3929 10.28. Procedure 27: SAVEFH - Save Current Filehandle 3931 SYNOPSIS 3933 (cfh) -> (sfh) 3935 ARGUMENT 3937 /* CURRENT_FH: */ 3938 void; 3940 RESULT 3942 struct SAVEFH4res { 3943 /* SAVED_FH: value of current fh */ 3944 nfsstat4status; 3945 }; 3947 DESCRIPTION 3949 Save the current filehandle. If a previous filehandle was saved 3950 then it is no longer accessible. The saved filehandle can be 3951 restored as the current filehandle with the RESTOREFH operator. 3953 IMPLEMENTATION 3955 ERRORS 3957 NFS4ERR_INVAL 3959 NFS4ERR_STALE 3961 NFS4ERR_BADHANDLE 3963 NFS4ERR_SERVERFAULT 3965 NFS4ERR_FHEXPIRED 3967 NFS4ERR_WRONGSEC 3969 10.29. Procedure 28: SECINFO - Obtain Available Security 3971 SYNOPSIS 3973 (cfh), filename -> { secinfo } 3975 ARGUMENT 3977 struct SECINFO4args { 3978 /* CURRENT_FH: */ 3979 filename4name; 3980 }; 3982 RESULT 3984 struct rpc_flavor_info { 3985 sec_oid4oid; 3986 qop4qop; 3987 rpc_gss_svc_t service; 3988 }; 3990 struct secinfo4 { 3991 rpc_flavor4flavor; 3992 rpc_flavor_info *flavor_info; 3993 secinfo4*nextentry; 3994 }; 3996 struct SECINFO4resok { 3997 secinfo4reply; 3998 }; 4000 union SECINFO4res switch (nfsstat4 status) { 4001 case NFS4_OK: 4002 SECINFO4resokresok4; 4003 default: 4004 void; 4005 }; 4007 DESCRIPTION 4009 The SECINFO procedure is used by the client to obtain a list of 4010 valid RPC authentication flavors for a specific file handle, file 4011 name pair. For the flavors, AUTH_NONE, AUTH_SYS, AUTH_DH, and 4012 AUTH_KRB4 no additional security information is returned. For a 4013 return value of AUTH_RPCSEC_GSS, a security triple is returned that 4014 contains the mechanism object id (as defined in [RFC2078]), the 4015 quality of protection (as defined in [RFC 2078]) and the service 4016 type (as defined in [RFC2203]). It is possible for SECINFO to 4017 return multiple entries with flavor equal to AUTH_RPCSEC_GSS with 4018 different security triple values. 4020 IMPLEMENTATION 4022 The SECINFO procedure is expected to be used by the NFS client when 4023 the error value of NFS4ERR_WRONGSEC is returned from another NFS 4024 procedure. This signifies to the client that the server's security 4025 policy is different from what the client is currently using. At 4026 this point, the client is expected to obtain a list of possible 4027 security flavors and choose what best suits its policies. 4029 ERRORS 4031 NFS4ERR_SERVERFAULT 4033 10.30. Procedure 29: SETATTR - Set Attributes 4035 SYNOPSIS 4037 (cfh), attrbits, attrvals -> - 4039 ARGUMENT 4041 struct SETATTR4args { 4042 /* CURRENT_FH: target object */ 4043 fattr4 obj_attributes; 4044 }; 4046 RESULT 4048 struct SETATTR4res { 4049 nfsstat4status; 4050 }; 4052 DESCRIPTION 4054 The SETATTR Procedure changes one or more of the attributes of a 4055 file system object. The new attributes are specified with a bitmap 4056 and the attributes that follow the bitmap in bit order. 4058 IMPLEMENTATION 4060 The file size attribute is used to request changes to the size of a 4061 file. A value of 0 (zero) causes the file to be truncated, a value 4062 less than the current size of the file causes data from new size to 4063 the end of the file to be discarded, and a size greater than the 4064 current size of the file causes logically zeroed data bytes to be 4065 added to the end of the file. Servers are free to implement this 4066 using holes or actual zero data bytes. Clients should not make any 4067 assumptions regarding a server's implementation of this feature, 4068 beyond that the bytes returned will be zeroed. Servers must support 4069 extending the file size via SETATTR. 4071 SETATTR is not guaranteed atomic. A failed SETATTR may partially 4072 change a file's attributes. 4074 Changing the size of a file with SETATTR indirectly changes the 4075 time_modify. A client must account for this as size changes can 4076 result in data deletion. 4078 If server and client times differ, programs that compare client 4079 time to file times can break. A time maintenance protocol should be 4080 used to limit client/server time skew. 4082 If the server cannot successfully set all the attributes it must 4083 return an NFS4ERR_INVAL error. If the server can only support 32 4084 bit offsets and sizes, a SETATTR request to set the size of a file 4085 to larger than can be represented in 32 bits will be rejected with 4086 this same error. 4088 ERRORS 4090 NFS4ERR_PERM 4092 NFS4ERR_IO 4094 NFS4ERR_ACCES 4096 NFS4ERR_INVAL 4098 NFS4ERR_FBIG 4100 NFS4ERR_NOSPC 4102 NFS4ERR_ROFS 4104 NFS4ERR_DQUOT 4106 NFS4ERR_STALE 4108 NFS4ERR_BADHANDLE 4110 NFS4ERR_NOTSUPP 4112 NFS4ERR_SERVERFAULT 4114 NFS4ERR_JUKEBOX 4116 NFS4ERR_DENIED 4118 NFS4ERR_GRACE 4120 NFS4ERR_FHEXPIRED 4121 NFS4ERR_WRONGSEC 4123 10.31. Procedure 30: SETCLIENTID - Negotiated Clientid 4125 SYNOPSIS 4127 verifier, client -> clientid 4129 ARGUMENT 4131 struct cid { 4132 opaque verifier<4>; 4133 opaque id<>; 4134 }; 4136 union nfs_client_id switch (clientid4 clientid) { 4137 case 0: 4138 cidident; 4139 default: 4140 void; 4141 }; 4143 struct SETCLIENTID4args { 4144 seqid4seqid; 4145 nfs_client_idclient; 4146 }; 4148 RESULT 4150 union SETCLIENTID4res switch (nfsstat4 status) { 4151 case NFS4_OK: 4152 clientid4clientid; 4153 default: 4154 void; 4155 }; 4157 DESCRIPTION 4159 The SETCLIENTID procedure introduces the ability of the client to 4160 notify the server of its intention to use a particular client 4161 identifier and verifier pair. Upon successful completion the 4162 server will return a clientid which is used in subsequent file 4163 locking requests. 4165 IMPLEMENTATION 4167 The server takes the verifier and client identification supplied 4168 and search for a match of the client identification. If no match 4169 is found the server saves the principal/uid information along with 4170 the verifier and client identification and returns a unique 4171 clientid that is used as a short hand reference to the supplied 4172 information. 4174 If the server find matching client identification and a 4175 corresponding match in principal/uid, the server releases all 4176 locking state for the client and returns a new clientid. 4178 ERRORS 4180 NFS4ERR_INVAL 4182 NFS4ERR_SERVERFAULT 4184 NFS4ERR_CLID_INUSE 4186 10.32. Procedure 31: VERIFY - Verify Same Attributes 4188 SYNOPSIS 4190 (cfh), attrbits, attrvals -> - 4192 ARGUMENT 4194 struct VERIFY4args { 4195 /* CURRENT_FH: object */ 4196 bitmap4 attr_request; 4197 fattr4 obj_attributes; 4198 }; 4200 RESULT 4202 struct VERIFY4res { 4203 nfsstat4status; 4204 }; 4206 DESCRIPTION 4208 The VERIFY procedure is used to verify that attributes have a value 4209 assumed by the client before proceeding with following operations 4210 in the compound request. For instance, a VERIFY can be used to 4211 make sure that the file size has not changed for an append-mode 4212 write: 4214 1. PUTFH 0x0123456 4215 2. VERIFY attrbits attrs 4216 3. WRITE 450328 4096 4218 If the attributes are not as expected, then the request fails and 4219 the data is not appended to the file. 4221 IMPLEMENTATION 4223 ERRORS 4224 NFS4ERR_ACCES 4226 NFS4ERR_INVAL 4228 NFS4ERR_STALE 4230 NFS4ERR_BADHANDLE 4232 NFS4ERR_NOTSUPP 4234 NFS4ERR_SERVERFAULT 4236 NFS4ERR_JUKEBOX 4238 NFS4ERR_FHEXPIRED 4240 10.33. Procedure 32: WRITE - Write to File 4242 SYNOPSIS 4244 (cfh), offset, count, stability, stateid, data -> count, committed, 4245 verifier 4247 ARGUMENT 4249 enum stable_how4 { 4250 UNSTABLE4 = 0, 4251 DATA_SYNC4 = 1, 4252 FILE_SYNC4 = 2 4253 }; 4255 struct WRITE4args { 4256 /* CURRENT_FH: file */ 4257 stateid4stateid; 4258 offset4offset; 4259 count4count; 4260 stable_how4stable; 4261 opaquedata<>; 4262 }; 4264 RESULT 4266 struct WRITE4resok { 4267 count4count; 4268 stable_how4committed; 4269 writeverf4verf; 4270 }; 4272 union WRITE4res switch (nfsstat4 status) { 4273 case NFS4_OK: 4274 WRITE4resokresok4; 4275 default: 4276 void; 4277 }; 4279 DESCRIPTION 4281 The WRITE procedure is used to write data to a regular file. The 4282 target file is specified by the current filehandle. The offset 4283 specifies the offset where the data should be written. An offset 4284 of 0 (zero) specifies that the write should start at the beginning 4285 of the file. The count represents the number of bytes of data that 4286 are to be written. If the count is 0 (zero), the WRITE will 4287 succeed and return a count of 0 (zero) subject to permissions 4288 checking. The server may choose to write fewer bytes than 4289 requested by the client. 4291 Part of the write request is a specification of how the write is to 4292 be performed. The client specifies with the stable parameter the 4293 method of how the data is to be processed by the server. If stable 4294 is FILE_SYNC, the server must commit the data written plus all file 4295 system metadata to stable storage before returning results. This 4296 corresponds to the NFS version 2 protocol semantics. Any other 4297 behavior constitutes a protocol violation. If stable is DATA_SYNC, 4298 then the server must commit all of the data to stable storage and 4299 enough of the metadata to retrieve the data before returning. The 4300 server implementor is free to implement DATA_SYNC in the same 4301 fashion as FILE_SYNC, but with a possible performance drop. If 4302 stable is UNSTABLE, the server is free to commit any part of the 4303 data and the metadata to stable storage, including all or none, 4304 before returning a reply to the client. There is no guarantee 4305 whether or when any uncommitted data will subsequently be committed 4306 to stable storage. The only guarantees made by the server are that 4307 it will not destroy any data without changing the value of verf and 4308 that it will not commit the data and metadata at a level less than 4309 that requested by the client. 4311 The stateid returned from a previous record lock or share 4312 reservation request is provided as part of the argument. The 4313 stateid is used by the server to verify that the associated lock is 4314 still valid and to update lease timeouts for the client. 4316 Upon successful completion, the following results are returned. 4317 The count result is the number of bytes of data written to the 4318 file. The server may write fewer bytes than requested. If so, the 4319 actual number of bytes written starting at location, offset, is 4320 returned. 4322 The server also returns an indication of the level of commitment of 4323 the data and metadata via committed. If the server committed all 4324 data and metadata to stable storage, committed should be set to 4325 FILE_SYNC. If the level of commitment was at least as strong as 4326 DATA_SYNC, then committed should be set to DATA_SYNC. Otherwise, 4327 committed must be returned as UNSTABLE. If stable was FILE_SYNC, 4328 then committed must also be FILE_SYNC: anything else constitutes a 4329 protocol violation. If stable was DATA_SYNC, then committed may be 4330 FILE_SYNC or DATA_SYNC: anything else constitutes a protocol 4331 violation. If stable was UNSTABLE, then committed may be either 4332 FILE_SYNC, DATA_SYNC, or UNSTABLE. 4334 The final portion of the result is the write verifier, verf. The 4335 write verifier is a cookie that the client can use to determine 4336 whether the server has changed state between a call to WRITE and a 4337 subsequent call to either WRITE or COMMIT. This cookie must be 4338 consistent during a single instance of the NFS version 4 protocol 4339 service and must be unique between instances of the NFS version 4 4340 protocol server, where uncommitted data may be lost. 4342 If a client writes data to the server with the stable argument set 4343 to UNSTABLE and the reply yields a committed response of DATA_SYNC 4344 or UNSTABLE, the client will follow up some time in the future with 4345 a COMMIT operation to synchronize outstanding asynchronous data and 4346 metadata with the server's stable storage, barring client error. It 4347 is possible that due to client crash or other error that a 4348 subsequent COMMIT will not be received by the server. 4350 IMPLEMENTATION 4352 It is possible for the server to write fewer than count bytes of 4353 data. In this case, the server should not return an error unless no 4354 data was written at all. If the server writes less than count 4355 bytes, the client should issue another WRITE to write the remaining 4356 data. 4358 It is assumed that the act of writing data to a file will cause the 4359 time_modified of the file to be updated. However, the time_modified 4360 of the file should not be changed unless the contents of the file 4361 are changed. Thus, a WRITE request with count set to 0 should not 4362 cause the time_modified of the file to be updated. 4364 The definition of stable storage has been historically a point of 4365 contention. The following expected properties of stable storage may 4366 help in resolving design issues in the implementation. Stable 4367 storage is persistent storage that survives: 4369 1. Repeated power failures. 4370 2. Hardware failures (of any board, power supply, etc.). 4371 3. Repeated software crashes, including reboot cycle. 4373 This definition does not address failure of the stable storage 4374 module itself. 4376 The verifier, is defined to allow a client to detect different 4377 instances of an NFS version 4 protocol server over which cached, 4378 uncommitted data may be lost. In the most likely case, the verifier 4379 allows the client to detect server reboots. This information is 4380 required so that the client can safely determine whether the server 4381 could have lost cached data. If the server fails unexpectedly and 4382 the client has uncommitted data from previous WRITE requests (done 4383 with the stable argument set to UNSTABLE and in which the result 4384 committed was returned as UNSTABLE as well) it may not have flushed 4385 cached data to stable storage. The burden of recovery is on the 4386 client and the client will need to retransmit the data to the 4387 server. 4389 A suggested verifier would be to use the time that the server was 4390 booted or the time the server was last started (if restarting the 4391 server without a reboot results in lost buffers). 4393 The committed field in the results allows the client to do more 4394 effective caching. If the server is committing all WRITE requests 4395 to stable storage, then it should return with committed set to 4396 FILE_SYNC, regardless of the value of the stable field in the 4397 arguments. A server that uses an NVRAM accelerator may choose to 4398 implement this policy. The client can use this to increase the 4399 effectiveness of the cache by discarding cached data that has 4400 already been committed on the server. 4402 Some implementations may return NFS4ERR_NOSPC instead of 4403 NFS4ERR_DQUOT when a user's quota is exceeded. 4405 ERRORS 4407 NFS4ERR_IO 4409 NFS4ERR_ACCES 4411 NFS4ERR_INVAL 4413 NFS4ERR_FBIG 4415 NFS4ERR_NOSPC 4417 NFS4ERR_ROFS 4419 NFS4ERR_DQUOT 4421 NFS4ERR_STALE 4422 NFS4ERR_BADHANDLE 4424 NFS4ERR_SERVERFAULT 4426 NFS4ERR_JUKEBOX 4428 NFS4ERR_LOCKED 4430 NFS4ERR_GRACE 4432 NFS4ERR_FHEXPIRED 4434 NFS4ERR_WRONGSEC 4436 11. Locking notes 4438 11.1. Short and long leases 4440 The usual lease trade-offs apply: short leases are good for fast 4441 server recovery at a cost of increased RENEW or READ (with zero 4442 length) requests. 4444 Longer leases are certainly kinder and gentler to large internet 4445 servers trying to handle huge numbers of clients. RENEW requests drop 4446 in direct proportion to the lease time. The disadvantages of long 4447 leases are slower server recover after crash (server must wait for 4448 leases to expire and grace period before granting new lock requests) 4449 and increased file contention (if client fails to transmit an unlock 4450 request then server must wait for lease expiration before granting 4451 new locks). 4453 Long leases are usable if the server is to store lease state in non- 4454 volatile memory. Upon recovery, the server can reconstruct the lease 4455 state from its non-volatile memory and continue operation with its 4456 clients and therefore long leases are not an issue. 4458 11.2. Clocks and leases 4460 To avoid the need for synchronized clocks, lease times are granted by 4461 the server as a time delta, though there is a requirement that the 4462 client and server clocks do not drift excessively over the duration 4463 of the lock. There is also the issue of propagation delay across the 4464 network which could easily be several hundred milliseconds across the 4465 Internet as well as the possibility that requests will be lost and 4466 need to be retransmitted. 4468 To take propagation delay into account, the client should subtract a 4469 it from lease times, e.g. if the client estimates the one-way 4470 propagation delay as 200 msec, then it can assume that the lease is 4471 already 200 msec old when it gets it. In addition, it'll take 4472 another 200 msec to get a response back to the server. So the client 4473 must send a lock renewal or write data back to the server 400 msec 4474 before the lease would expire. 4476 The client could measure propagation delay with reasonable accuracy 4477 by measuring the round-trip time for lock extensions assuming that 4478 there's not much server processing overhead in an extension. 4480 11.3. Locks and lease times 4482 Lock requests do not contain desired lease times. The server 4483 allocates leases with no information from the client. The assumption 4484 here is that the client really has no idea of just how long the lock 4485 will be required. If a scenario can be found where a hint from the 4486 client as to the maximum lease time desired would be useful, then 4487 this feature could be added to lock requests. 4489 11.4. Locking of directories and other meta-files 4491 A question: should directories and/or other file-system objects like 4492 symbolic links be lockable ? Clients will want to cache whole 4493 directories. It would be nice to have consistent directory caches, 4494 but it would require that any client creating a new file get a write 4495 lock on the directory and be prepared to handle lock denial. Is the 4496 weak cache consistency that we currently have for directories 4497 acceptable ? I think perhaps it is - given the expense of doing full 4498 consistency on an Internet scale. 4500 11.5. Proxy servers and leases 4502 Proxy servers. There is some interest in having NFS V4 support 4503 caching proxies. Support for proxy caching is a requirement if 4504 servers are to handle large numbers of clients - clients that may 4505 have little or no ability to cache on their own. How could proxy 4506 servers use lease-based locking ? 4508 11.6. Locking and the new latency 4510 Latency caused by locking. If a client wants to update a file then 4511 it will have to wait until the leases on read locks have expired. If 4512 the leases are of the order of 60 seconds or several minutes then the 4513 client (and end-user) may be blocked for a while. This is unfamiliar 4514 for current NFS users who are not bothered by mandatory locking - but 4515 it could be an issue if we decide we like the caching benefits. A 4516 similar problem exists for clients that wish to read a file that is 4517 write locked. The read-lock case is likely to be more common if 4518 read-locking is used to protect cached data on the client. 4520 12. Internationalization 4522 The primary issue in which NFS needs to deal with 4523 internationalization, or i18n, is with respect to file names and 4524 other strings as used within the protocol. NFS' choice of string 4525 representation must allow reasonable name/string access to clients 4526 which use various languages. The UTF-8 encoding allows for this type 4527 of access and this choice is explained in the following. 4529 12.1. Universal Versus Local Character Sets 4531 [RFC1345] describes a table of 16 bit characters for many different 4532 languages (the bit encodings match Unicode, though of course RFC1345 4533 is somewhat out of date with respect to current Unicode assignments). 4534 Each character from each language has a unique 16 bit value in the 16 4535 bit character set. Thus this table can be thought of as a universal 4536 character set. [RFC1345] then talks about groupings of subsets of the 4537 entire 16 bit character set into "Charset Tables". For example one 4538 might take all the Greek characters from the 16 bit table (which are 4539 are consecutively allocated), and normalize their offsets to a table 4540 that fits in 7 bits. Thus we find that "lower case alpha" is in the 4541 same position as "upper case a" in the US-ASCII table, and "upper 4542 case alpha" is in the same position as "lower case a" in the US-ASCII 4543 table. 4545 These normalized subset character sets can be thought of as "local 4546 character sets", suitable for an operating system locale. 4548 Local character sets are not suitable for the NFS protocol. Consider 4549 someone who creates a file with a name in a Swedish character set. If 4550 someone else later goes to access the file with their locale set to 4551 the Swedish language, then there are no problems. But if someone in 4552 say the US-ASCII locale goes to access the file, the file name will 4553 look very different, because the Swedish characters in the 7 bit 4554 table will now be represented in US-ASCII characters on the display. 4555 It would be preferable to give the US-ASCII user a way to display the 4556 file name using Swedish glyphs. In order to do that, the NFS protocol 4557 would have to include the locale with the file name on each operation 4558 to create a file. 4560 But then what of the situation when we have a path name on the server 4561 like: 4563 /component-1/component-2/component-3 4565 Each component could have been created with a different locale. If 4566 one issues CREATE with multi-component path name, and if some of the 4567 leading components already exist, what is to be done with the 4568 existing components? Is the current locale attribute replaced with 4569 the user's current one? These types of situations quickly become too 4570 complex when there is an alternate solution. 4572 If NFS V4 used a universal 16 bit or 32 bit character set (or a 4573 encoding of a 16 bit or 32 bit character set into octets), then 4574 server and client need not care if the locale of the user accessing 4575 the file is different than the locale of the user who created the 4576 file. The unique 16 bit or 32 bit encoding of the character allows 4577 for determination of what language the character is from and also how 4578 to display that character on the client. The server need not know 4579 what locales are used. 4581 12.2. Overview of Universal Character Set Standards 4583 The previous section makes a case for using a universal character set 4584 in NFS version 4. This section makes the case for using UTF-8 as the 4585 specific universal character set for NFS version 4. 4587 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 4588 Unicode, and UCS-*. There are two standards bodies managing universal 4589 code sets: 4591 o ISO/IEC which has the standard 10646-1 4593 o Unicode which has the Unicode standard 4595 Both standards bodies have pledged to track each other's assignments 4596 of character codes. 4598 The following is a brief analysis of the various standards. 4600 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 4601 multi-octet character set called the Universal Character 4602 Set (UCS), which encompasses most of the world's writing 4603 systems." 4605 UCS-2 a two octet per character encoding that addresses the first 4606 2^16 characters of UCS. Currently there are no UCS 4607 characters beyond that range. 4609 UCS-4 a four octet per character encoding that permits the 4610 encoding of up to 2^31 characters. 4612 UTF UCS transformation format. 4614 UTF-1 Only historical interest; it has been removed from 10646-1 4616 UTF-7 Encodes the entire "repertoire" of UCS "characters using 4617 only octets with the higher order bit clear". [RFC2152] 4618 describes UTF-7. UTF-7 accomplishes this by reserving one 4619 of the 7bit US-ASCII characters as a "shift" character to 4620 indicate non-US-ASCII characters. 4622 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 4623 characters are encoded as before unchanged. Any octet with 4624 the high bit cleared can only mean a US-ASCII character. 4625 The high bit set means that a UCS character is being 4626 encoded. 4628 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 4629 reserved range in UCS-2. 4631 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 4633 Up to the present time, changes in Unicode and amendments 4634 to ISO/IEC 10646 have tracked each other, so that the 4635 character repertoires and code point assignments have 4636 remained in sync. The relevant standardization committees 4637 have committed to maintain this very useful synchronism. 4639 12.3. Difficulties with UCS-4, UCS-2, Unicode 4641 Adapting existing applications, and file systems to multi-octet 4642 schemes like UCS and Unicode can be difficult. A significant amount 4643 of code has been written to process streams of bytes. Also there are 4644 many existing stored objects described with 7 bit or 8 bit 4645 characters. Doubling or quadrupling the bandwidth and storage 4646 requirements seems like an expensive way to accomplish I18N. 4648 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 4649 enough but, according to [Unicode1], 38,887 Unicode characters are 4650 already assigned. And according to [Unicode2] there are still more 4651 languages that need to be added. 4653 12.4. UTF-8 and its solutions 4655 UTF-8 solves problems for NFS that exist with the use of UCS and 4656 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 4657 that will be compact for most users. The encoding table from UCS-4 to 4658 UTF-8, as copied from [RFC2279]: 4660 UCS-4 range (hex.) UTF-8 octet sequence (binary) 4661 0000 0000-0000 007F 0xxxxxxx 4662 0000 0080-0000 07FF 110xxxxx 10xxxxxx 4663 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 4665 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 4666 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4667 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4668 10xxxxxx 4670 See [RFC2279] for precise encoding and decoding rules. Note because 4671 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 4672 for the reserved range between D800 and DFFF. 4674 Note that the 16 bit UCS or Unicode characters require no more than 3 4675 octets to encode into UTF-8 4677 Interestingly, UTF-8 has room to handle characters larger than 31 4678 bits, because the leading octet of form: 4680 1111111x 4682 is not defined. If needed, ISO could either use that octet to 4683 indicate a sequence of an encoded 8 octet character, or perhaps use 4684 11111110 to permit the next octet to indicate an even more expandable 4685 character set. 4687 So using UTF-8 to represent character encodings means never having to 4688 run out of room. 4690 13. Security Considerations 4692 The major security feature to consider is the authentication of the 4693 user making the request of NFS service. Consideration should also be 4694 given to the integrity and privacy of this NFS request. These 4695 specific issues are discussed as part of the section on "RPC and 4696 Security Flavor". 4698 As this document progresses, other issues of denial of service and 4699 other typical security issues will be addressed here along with those 4700 issues specific to NFS service. 4702 14. NFS Version 4 RPC definition file 4704 /* 4705 * nfs_prot.x 4706 * 4707 */ 4709 %#pragma ident "@(#)nfs4_prot.x 1.32 99/06/25" 4711 /* 4712 * Sizes 4713 */ 4714 const NFS4_FHSIZE = 128; 4715 const NFS4_CREATEVERFSIZE = 8; 4717 /* 4718 * Timeval 4719 */ 4720 struct nfstime4 { 4721 int64_t seconds; 4722 uint32_t nseconds; 4723 }; 4725 struct specdata4 { 4726 uint32_t specdata1; 4727 uint32_t specdata2; 4728 }; 4730 struct bitmap4 { 4731 uint32_t bits<>; 4732 }; 4734 /* 4735 * Basic data types 4736 */ 4737 typedef opaque utf8string<>; 4738 typedef uint64_t offset4; 4739 typedef uint32_t count4; 4740 typedef uint32_t length4; 4741 typedef uint64_t clientid4; 4742 typedef uint64_t stateid4; 4743 typedef uint32_t seqid4; 4744 typedef uint32_t writeverf4; 4745 typedef opaque createverf4[NFS4_CREATEVERFSIZE]; 4746 typedef utf8string filename4; 4747 typedef uint64_t nfs_lockid4; 4748 typedef uint32_t nfs_lease4; 4749 typedef uint32_t nfs_lockstate4; 4750 typedef uint64_t nfs_cookie4; 4751 typedef utf8string linktext4; 4752 typedef opaque sec_oid4<>; 4753 typedef uint32_t qop4; 4755 typedef uint32_t fattr4_type; 4756 typedef bool fattr4_persistent_fh; 4757 typedef uint64_t fattr4_change; 4758 typedef uint64_t fattr4_size; 4759 typedef bool fattr4_link_support; 4760 typedef bool fattr4_symlink_support; 4761 typedef bool fattr4_named_attr; 4762 typedef uint64_t fattr4_fsid_major; 4763 typedef uint64_t fattr4_fsid_minor; 4765 typedef bool fattr4_archive; 4766 typedef bool fattr4_cansettime; 4767 typedef bool fattr4_case_insensitive; 4768 typedef bool fattr4_case_preserving; 4769 typedef bool fattr4_chown_restricted; 4770 typedef uint64_t fattr4_fileid; 4771 typedef uint64_t fattr4_files_avail; 4772 typedef uint64_t fattr4_files_free; 4773 typedef uint64_t fattr4_files_total; 4774 typedef bool fattr4_hidden; 4775 typedef bool fattr4_homogenous; 4776 typedef uint64_t fattr4_maxfilesize; 4777 typedef uint32_t fattr4_maxlink; 4778 typedef uint32_t fattr4_maxname; 4779 typedef uint64_t fattr4_maxread; 4780 typedef uint64_t fattr4_maxwrite; 4781 typedef utf8string fattr4_mimetype; 4782 typedef uint32_t fattr4_mode; 4783 typedef bool fattr4_no_trunc; 4784 typedef uint32_t fattr4_numlinks; 4785 typedef utf8string fattr4_owner; 4786 typedef utf8string fattr4_owner_group; 4787 typedef uint64_t fattr4_quota_hard; 4788 typedef uint64_t fattr4_quota_soft; 4789 typedef uint64_t fattr4_quota_used; 4790 typedef specdata4 fattr4_rawdev; 4791 typedef uint64_t fattr4_space_avail; 4792 typedef uint64_t fattr4_space_free; 4793 typedef uint64_t fattr4_space_total; 4794 typedef uint64_t fattr4_space_used; 4795 typedef bool fattr4_system; 4796 typedef nfstime4 fattr4_time_access; 4797 typedef nfstime4 fattr4_time_backup; 4798 typedef nfstime4 fattr4_time_create; 4799 typedef nfstime4 fattr4_time_delta; 4800 typedef nfstime4 fattr4_time_metadata; 4801 typedef nfstime4 fattr4_time_modify; 4802 typedef utf8string fattr4_version; 4803 typedef nfstime4 fattr4_volatility; 4805 /* 4806 * Error status 4807 */ 4808 enum nfsstat4 { 4809 NFS4_OK = 0, 4810 NFS4ERR_PERM = 1, 4811 NFS4ERR_NOENT = 2, 4812 NFS4ERR_IO = 5, 4813 NFS4ERR_NXIO = 6, 4814 NFS4ERR_ACCES = 13, 4815 NFS4ERR_EXIST = 17, 4816 NFS4ERR_XDEV = 18, 4817 NFS4ERR_NODEV = 19, 4818 NFS4ERR_NOTDIR = 20, 4819 NFS4ERR_ISDIR = 21, 4820 NFS4ERR_INVAL = 22, 4821 NFS4ERR_FBIG = 27, 4822 NFS4ERR_NOSPC = 28, 4823 NFS4ERR_ROFS = 30, 4824 NFS4ERR_MLINK = 31, 4825 NFS4ERR_NAMETOOLONG = 63, 4826 NFS4ERR_NOTEMPTY = 66, 4827 NFS4ERR_DQUOT = 69, 4828 NFS4ERR_STALE = 70, 4829 NFS4ERR_BADHANDLE = 10001, 4830 NFS4ERR_NOT_SYNC = 10002, 4831 NFS4ERR_BAD_COOKIE = 10003, 4832 NFS4ERR_NOTSUPP = 10004, 4833 NFS4ERR_TOOSMALL = 10005, 4834 NFS4ERR_SERVERFAULT = 10006, 4835 NFS4ERR_BADTYPE = 10007, 4836 NFS4ERR_JUKEBOX = 10008, 4837 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 4838 NFS4ERR_DENIED = 10010,/* lock unavailable */ 4839 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 4840 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 4841 NFS4ERR_GRACE = 10013,/* in grace period */ 4842 NFS4ERR_FHEXPIRED = 10014,/* file handle expired */ 4843 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 4844 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 4845 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 4846 NFS4ERR_RESOURCE = 10018 /* resource exhaustion */ 4847 }; 4849 enum rpc_flavor4 { 4850 AUTH4_NONE = 0, 4851 AUTH4_SYS = 1, 4852 AUTH4_DH = 2, 4853 AUTH4_KRB4 = 3, 4854 AUTH4_RPCSEC_GSS = 4 4855 }; 4857 /* 4858 * From RFC 2203 4859 */ 4860 enum rpc_gss_svc_t { 4861 RPC_GSS_SVC_NONE = 1, 4862 RPC_GSS_SVC_INTEGRITY = 2, 4863 RPC_GSS_SVC_PRIVACY = 3 4864 }; 4866 /* 4867 * File access handle 4868 */ 4869 struct nfs4_fh { 4870 opaque data; 4871 }; 4873 /* 4874 * File types 4875 */ 4876 enum nfs4_ftype { 4877 NF4REG = 1, /* Regular File */ 4878 NF4DIR = 2, /* Directory */ 4879 NF4BLK = 3, /* Special File - block device */ 4880 NF4CHR = 4, /* Special File - character device */ 4881 NF4LNK = 5, /* Symbolic Link */ 4882 NF4SOCK = 6, /* Special File - socket */ 4883 NF4FIFO = 7, /* Special File - fifo */ 4884 NF4ATTRDIR = 8, /* Attribute Directory */ 4885 NF4NAMEDATTR = 9 /* Named Attribute */ 4886 }; 4888 /* 4889 * Mandatory Attributes 4890 */ 4891 const FATTR4_SUPPORTED_ATTRS = 0; 4892 const FATTR4_TYPE = 1; 4893 const FATTR4_PERSISTENT_FH = 2; 4894 const FATTR4_CHANGE = 3; 4895 const FATTR4_SIZE = 4; 4896 const FATTR4_LINK_SUPPORT = 5; 4897 const FATTR4_SYMLINK_SUPPORT = 6; 4898 const FATTR4_NAMED_ATTR = 7; 4899 const FATTR4_FSID_MAJOR = 8; 4900 const FATTR4_FSID_MINOR = 9; 4902 /* 4903 * Recommended Attributes 4904 */ 4905 const FATTR4_ACL = 10; 4906 const FATTR4_ARCHIVE = 11; 4907 const FATTR4_CANSETTIME = 12; 4908 const FATTR4_CASE_INSENSITIVE = 13; 4909 const FATTR4_CASE_PRESERVING = 14; 4910 const FATTR4_CHOWN_RESTRICTED = 15; 4911 const FATTR4_FILEHANDLE = 16; 4912 const FATTR4_FILEID = 17; 4913 const FATTR4_FILES_AVAIL = 18; 4914 const FATTR4_FILES_FREE = 19; 4915 const FATTR4_FILES_TOTAL = 20; 4916 const FATTR4_HIDDEN = 21; 4917 const FATTR4_HOMOGENEOUS = 22; 4918 const FATTR4_MAXFILESIZE = 23; 4919 const FATTR4_MAXLINK = 24; 4920 const FATTR4_MAXNAME = 25; 4921 const FATTR4_MAXREAD = 26; 4922 const FATTR4_MAXWRITE = 27; 4923 const FATTR4_MIME_TYPE = 28; 4924 const FATTR4_MODE = 29; 4925 const FATTR4_NO_TRUNC = 30; 4926 const FATTR4_NUMLINKS = 31; 4927 const FATTR4_OWNER = 32; 4928 const FATTR4_OWNER_GROUP = 33; 4929 const FATTR4_QUOTA_HARD = 34; 4930 const FATTR4_QUOTA_SOFT = 35; 4931 const FATTR4_QUOTA_USED = 36; 4932 const FATTR4_RAWDEV = 37; 4933 const FATTR4_SPACE_AVAIL = 38; 4934 const FATTR4_SPACE_FREE = 39; 4935 const FATTR4_SPACE_TOTAL = 40; 4936 const FATTR4_SPACE_USED = 41; 4937 const FATTR4_SYSTEM = 42; 4938 const FATTR4_TIME_ACCESS = 43; 4939 const FATTR4_TIME_BACKUP = 44; 4940 const FATTR4_TIME_CREATE = 45; 4941 const FATTR4_TIME_DELTA = 46; 4942 const FATTR4_TIME_METADATA = 47; 4943 const FATTR4_TIME_MODIFY = 48; 4944 const FATTR4_VERSION = 49; 4945 const FATTR4_VOLATILITY = 50; 4947 struct attrlist { 4948 opaque attrs<>; 4949 }; 4951 struct fattr4 { 4952 bitmap4 attrmask; 4953 attrlist attr_vals; 4954 }; 4956 struct cid { 4957 opaque verifier<4>; 4958 opaque id<>; 4959 }; 4961 union nfs_client_id switch (clientid4 clientid) { 4962 case 0: 4963 cid ident; 4964 default: 4965 void; 4966 }; 4968 struct lockown { 4969 clientid4 clientid; 4970 opaque owner<>; 4971 }; 4973 union nfs_lockowner switch (stateid4 stateid) { 4974 case 0: 4975 lockown ident; 4976 default: 4977 void; 4978 }; 4980 enum nfs4_lock_type { 4981 READ_LT = 1, 4982 WRITE_LT = 2, 4983 READW_LT = 3, /* blocking read */ 4984 WRITEW_LT = 4 /* blocking write */ 4985 }; 4987 /* 4988 * ACCESS: Check access permission 4989 */ 4990 const ACCESS4_READ = 0x0001; 4991 const ACCESS4_LOOKUP = 0x0002; 4992 const ACCESS4_MODIFY = 0x0004; 4993 const ACCESS4_EXTEND = 0x0008; 4994 const ACCESS4_DELETE = 0x0010; 4995 const ACCESS4_EXECUTE = 0x0020; 4997 struct ACCESS4args { 4998 /* CURRENT_FH: object */ 4999 uint32_t access; 5000 }; 5002 struct ACCESS4resok { 5003 uint32_t access; 5004 }; 5006 union ACCESS4res switch (nfsstat4 status) { 5007 case NFS4_OK: 5008 ACCESS4resok resok4; 5009 default: 5010 void; 5011 }; 5013 /* 5014 * COMMIT: Commit cached data on server to stable storage 5015 */ 5016 struct COMMIT4args { 5017 /* CURRENT_FH: file */ 5018 offset4 offset; 5019 count4 count; 5020 }; 5022 struct COMMIT4resok { 5023 writeverf4 verf; 5024 }; 5026 union COMMIT4res switch (nfsstat4 status) { 5027 case NFS4_OK: 5028 COMMIT4resok resok4; 5029 default: 5030 void; 5031 }; 5033 /* 5034 * CREATE: Create a file 5035 */ 5037 enum createmode4 { 5038 UNCHECKED4 = 0, 5039 GUARDED4 = 1, 5040 EXCLUSIVE4 = 2 5041 }; 5043 union createhow4 switch (createmode4 mode) { 5044 case UNCHECKED4: 5045 case GUARDED4: 5046 fattr4 createattrs; 5047 case EXCLUSIVE4: 5048 createverf4 verf; 5049 }; 5051 const ACCESS4_READ = 0x0001; 5052 const ACCESS4_MODIFY = 0x0002; 5053 const ACCESS4_LOOKUP = 0x0004; 5054 const ACCESS4_EXTEND = 0x0008; 5055 const ACCESS4_DELETE = 0x0010; 5056 const ACCESS4_EXECUTE = 0x0020; 5058 enum opentype4 { 5059 OPEN4_NOCREATE = 0, 5060 OPEN4_CREATE = 1 5061 }; 5063 union openflag switch (opentype4 opentype) { 5064 case OPEN4_CREATE: 5065 createhow4 how; 5066 default: 5067 void; 5068 }; 5070 /* 5071 * LOCK/LOCKT/LOCKU: Record lock management 5072 */ 5073 struct LOCK4args { 5074 /* CURRENT_FH: file */ 5075 nfs4_lock_type type; 5076 seqid4 seqid; 5077 bool reclaim; 5078 nfs_lockowner owner; 5079 offset4 offset; 5080 length4 length; 5081 }; 5083 struct lockres { 5084 stateid4 stateid; 5085 int32_t access; 5086 }; 5088 union LOCK4res switch (nfsstat4 status) { 5089 case NFS4_OK: 5090 lockres result; 5091 default: 5092 void; 5093 }; 5095 union LOCKT4res switch (nfsstat4 status) { 5096 case NFS4ERR_DENIED: 5097 nfs_lockowner owner; 5098 case NFS4_OK: 5099 void; 5100 default: 5101 void; 5102 }; 5104 union LOCKU4res switch (nfsstat4 status) { 5105 case NFS4_OK: 5106 stateid4 stateid_ok; 5107 default: 5108 stateid4 stateid_oth; 5109 }; 5111 /* 5112 * SETCLIENTID 5113 */ 5114 struct SETCLIENTID4args { 5115 seqid4 seqid; 5116 nfs_client_id client; 5117 }; 5119 union SETCLIENTID4res switch (nfsstat4 status) { 5120 case NFS4_OK: 5121 clientid4 clientid; 5122 default: 5123 void; 5124 }; 5126 /* 5127 * Access and Deny constants for open argument 5128 */ 5129 const OPEN4_ACCESS_READ = 0x0001; 5130 const OPEN4_ACCESS_WRITE= 0x0002; 5131 const OPEN4_ACCESS_BOTH = 0x0003; 5132 const OPEN4_DENY_NONE = 0x0000; 5133 const OPEN4_DENY_READ = 0x0001; 5134 const OPEN4_DENY_WRITE = 0x0002; 5135 const OPEN4_DENY_BOTH = 0x0003; 5137 union open_nameoffh switch (bool reclaim_fh) { 5138 case FALSE: 5139 /* CURRENT_FH: directory */ 5140 filename4 filenames<>; 5141 case TRUE: 5142 /* CURRENT_FH: file on reclaim */ 5143 void; 5144 }; 5146 /* 5147 * OPEN: Open a file, potentially with a share lock 5148 */ 5149 struct OPEN4args { 5150 open_nameorfh file; 5151 openflag openhow; 5152 nfs_lockowner owner; 5153 seqid4 seqid; 5154 bool reclaim; 5155 int32_t access; 5156 int32_t deny; 5157 }; 5159 union OPEN4res switch (nfsstat4 status) { 5160 case NFS4_OK: 5161 /* CURRENT_FH: opened file */ 5162 LOCK4res resok4; 5163 default: 5164 void; 5165 }; 5167 /* 5168 * CREATE: Create special file 5169 */ 5170 struct CREATE4args { 5171 /* CURRENT_FH: directory for creation */ 5172 filename4 objname; 5173 fattr4_type type; 5174 createhow4 createhow; 5175 }; 5177 struct CREATE4res { 5178 nfsstat4 status; 5180 }; 5182 /* 5183 * CLOSE: Close a file and release share locks 5184 */ 5185 struct CLOSE4args { 5186 stateid4 stateid; 5187 }; 5189 union CLOSE4res switch (nfsstat4 status) { 5190 case NFS4_OK: 5191 stateid4 stateid; 5192 default: 5193 void; 5194 }; 5196 /* 5197 * GETATTR: Get file attributes 5198 */ 5199 struct GETATTR4args { 5200 /* CURRENT_FH: directory or file */ 5201 bitmap4 attr_request; 5202 }; 5204 struct GETATTR4resok { 5205 fattr4 obj_attributes; 5206 }; 5208 union GETATTR4res switch (nfsstat4 status) { 5209 case NFS4_OK: 5210 GETATTR4resok resok4; 5211 default: 5212 void; 5213 }; 5215 /* 5216 * OPENATTR: open named attributes directory 5217 */ 5218 struct OPENATTR4res { 5219 /* CURRENT_FH: name attr directory*/ 5220 nfsstat4 status; 5221 }; 5223 /* 5224 * GETFH: Get current filehandle 5225 */ 5226 struct GETFH4resok { 5227 nfs4_fh object; 5228 }; 5230 union GETFH4res switch (nfsstat4 status) { 5231 case NFS4_OK: 5232 GETFH4resok resok4; 5233 default: 5234 void; 5235 }; 5237 /* 5238 * LINK: Create link to an object 5239 */ 5240 struct LINK4args { 5241 /* CURRENT_FH: file */ 5242 nfs4_fh dir; 5243 filename4 newname; 5244 }; 5246 struct LINK4res { 5247 nfsstat4 status; 5248 }; 5250 /* 5251 * LOOKUP: Lookup filename 5252 */ 5253 struct LOOKUP4args { 5254 /* CURRENT_FH: directory */ 5255 filename4 filenames<>; 5256 }; 5258 struct LOOKUP4res { 5259 /* CURRENT_FH: object */ 5260 nfsstat4 status; 5261 }; 5263 /* 5264 * LOOKUPP: Lookup parent directory 5265 */ 5266 struct LOOKUPP4res { 5267 /* CURRENT_FH: directory */ 5268 nfsstat4 status; 5269 }; 5271 /* 5272 * NVERIFY: Verify attributes different 5273 */ 5274 struct NVERIFY4args { 5275 /* CURRENT_FH: object */ 5276 bitmap4 attr_request; 5277 fattr4 obj_attributes; 5278 }; 5280 struct NVERIFY4res { 5281 nfsstat4 status; 5282 }; 5284 /* 5285 * RESTOREFH: Restore saved filehandle 5286 */ 5288 struct RESTOREFH4res { 5289 /* CURRENT_FH: value of saved fh */ 5290 nfsstat4 status; 5291 }; 5293 /* 5294 * SAVEFH: Save current filehandle 5295 */ 5296 struct SAVEFH4res { 5297 /* SAVED_FH: value of current fh */ 5298 nfsstat4 status; 5299 }; 5301 /* 5302 * PUTFH: Set current filehandle 5303 */ 5304 struct PUTFH4args { 5305 nfs4_fh object; 5306 }; 5308 struct PUTFH4res { 5309 /* CURRENT_FH: */ 5310 nfsstat4 status; 5311 }; 5313 /* 5314 * PUTROOTFH: Set root filehandle 5315 */ 5316 struct PUTROOTFH4res { 5317 /* CURRENT_FH: root fh */ 5318 nfsstat4 status; 5319 }; 5321 /* 5322 * PUTPUBFH: Set public filehandle 5323 */ 5324 struct PUTPUBFH4res { 5325 /* CURRENT_FH: public fh */ 5326 nfsstat4 status; 5327 }; 5329 /* 5330 * READ: Read from file 5331 */ 5332 struct READ4args { 5333 /* CURRENT_FH: file */ 5334 stateid4 stateid; 5335 offset4 offset; 5336 count4 count; 5337 }; 5339 struct READ4resok { 5340 bool eof; 5341 opaque data<>; 5342 }; 5344 union READ4res switch (nfsstat4 status) { 5345 case NFS4_OK: 5346 READ4resok resok4; 5347 default: 5348 void; 5349 }; 5351 /* 5352 * READDIR: Read directory 5353 */ 5354 struct READDIR4args { 5355 /* CURRENT_FH: directory */ 5356 nfs_cookie4 cookie; 5357 count4 dircount; 5358 count4 maxcount; 5359 bitmap4 attr_request; 5361 }; 5363 struct entry4 { 5364 nfs_cookie4 cookie; 5365 filename4 name; 5366 fattr4 attrs; 5367 entry4 *nextentry; 5368 }; 5370 struct dirlist4 { 5371 entry4 *entries; 5372 bool eof; 5373 }; 5375 struct READDIR4resok { 5376 dirlist4 reply; 5377 }; 5379 union READDIR4res switch (nfsstat4 status) { 5380 case NFS4_OK: 5381 READDIR4resok resok4; 5382 default: 5383 void; 5384 }; 5386 /* 5387 * READLINK: Read symbolic link 5388 */ 5389 struct READLINK4resok { 5390 linktext4 link; 5391 }; 5393 union READLINK4res switch (nfsstat4 status) { 5394 case NFS4_OK: 5395 READLINK4resok resok4; 5396 default: 5397 void; 5398 }; 5400 /* 5401 * REMOVE: Remove filesystem object 5402 */ 5403 struct REMOVE4args { 5404 /* CURRENT_FH: directory */ 5405 filename4 target; 5406 }; 5408 struct REMOVE4res { 5409 nfsstat4 status; 5410 }; 5412 /* 5413 * RENAME: Rename directory entry 5414 */ 5415 struct RENAME4args { 5416 /* CURRENT_FH: source directory */ 5417 filename4 oldname; 5418 nfs4_fh newdir; 5419 filename4 newname; 5420 }; 5422 struct RENAME4res { 5423 nfsstat4 status; 5424 }; 5426 /* 5427 * RENEW: Renew a Lease 5428 */ 5429 struct RENEW4args { 5430 stateid4 stateid; 5431 }; 5433 struct RENEW4res { 5434 nfsstat4 status; 5435 }; 5437 /* 5438 * SETATTR: Set attributes 5439 */ 5440 struct SETATTR4args { 5441 /* CURRENT_FH: target object */ 5442 fattr4 obj_attributes; 5443 }; 5445 struct SETATTR4res { 5446 nfsstat4 status; 5447 }; 5449 /* 5450 * VERIFY: Verify attributes same 5451 */ 5452 struct VERIFY4args { 5453 /* CURRENT_FH: object */ 5454 bitmap4 attr_request; 5455 fattr4 obj_attributes; 5456 }; 5458 struct VERIFY4res { 5459 nfsstat4 status; 5460 }; 5462 /* 5463 * WRITE: Write to file 5464 */ 5466 enum stable_how4 { 5467 UNSTABLE4 = 0, 5468 DATA_SYNC4 = 1, 5469 FILE_SYNC4 = 2 5470 }; 5472 struct WRITE4args { 5473 /* CURRENT_FH: file */ 5474 stateid4 stateid; 5475 offset4 offset; 5476 count4 count; 5477 stable_how4 stable; 5478 opaque data<>; 5479 }; 5481 struct WRITE4resok { 5482 count4 count; 5483 stable_how4 committed; 5484 writeverf4 verf; 5485 }; 5487 union WRITE4res switch (nfsstat4 status) { 5488 case NFS4_OK: 5489 WRITE4resok resok4; 5490 default: 5491 void; 5492 }; 5494 /* 5495 * SECINFO: Obtain Available Security Mechanisms 5496 */ 5497 struct SECINFO4args { 5498 /* CURRENT_FH: */ 5499 filename4 name; 5500 }; 5502 struct rpc_flavor_info { 5503 sec_oid4 oid; 5504 qop4 qop; 5505 rpc_gss_svc_t service; 5506 }; 5508 struct secinfo4 { 5509 rpc_flavor4 flavor; 5510 rpc_flavor_info *flavor_info; 5511 secinfo4 *nextentry; 5512 }; 5513 struct SECINFO4resok { 5514 secinfo4 reply; 5515 }; 5517 union SECINFO4res switch (nfsstat4 status) { 5518 case NFS4_OK: 5519 SECINFO4resok resok4; 5520 default: 5521 void; 5522 }; 5524 enum opcode { 5525 OP_ACCESS = 2, 5526 OP_CLOSE = 3, 5527 OP_COMMIT = 4, 5528 OP_CREATE = 5, 5529 OP_GETATTR = 6, 5530 OP_GETFH = 7, 5531 OP_LINK = 8, 5532 OP_LOCK = 9, 5533 OP_LOCKT = 10, 5534 OP_LOCKU = 11, 5535 OP_LOOKUP = 12, 5536 OP_LOOKUPP = 13, 5537 OP_NVERIFY = 14, 5538 OP_OPEN = 15, 5539 OP_OPENATTR = 16, 5540 OP_PUTFH = 17, 5541 OP_PUTPUBFH = 18, 5542 OP_PUTROOTFH = 19, 5543 OP_READ = 20, 5544 OP_READDIR = 21, 5545 OP_READLINK = 22, 5546 OP_REMOVE = 23, 5547 OP_RENAME = 24, 5548 OP_RENEW = 25, 5549 OP_RESTOREFH = 26, 5550 OP_SAVEFH = 27, 5551 OP_SECINFO = 28, 5552 OP_SETATTR = 29, 5553 OP_SETCLIENTID = 30, 5554 OP_VERIFY = 31, 5555 OP_WRITE = 32 5556 }; 5558 union opunion switch (unsigned opcode) { 5559 case OP_ACCESS: ACCESS4args opaccess; 5560 case OP_CLOSE: CLOSE4args opclose; 5561 case OP_COMMIT: COMMIT4args opcommit; 5562 case OP_CREATE: CREATE4args opcreate; 5563 case OP_GETATTR: GETATTR4args opgettattr; 5564 case OP_GETFH: void; 5565 case OP_LINK: LINK4args oplink; 5566 case OP_LOCK: LOCK4args oplock; 5567 case OP_LOCKT: LOCK4args oplockt; 5568 case OP_LOCKU: LOCK4args oplocku; 5569 case OP_LOOKUP: LOOKUP4args oplookup; 5570 case OP_LOOKUPP: void; 5571 case OP_NVERIFY: NVERIFY4args opnverify; 5572 case OP_OPEN: OPEN4args opopen; 5573 case OP_OPENATTR: void; 5574 case OP_PUTFH: PUTFH4args opputfh; 5575 case OP_PUTPUBFH: void; 5576 case OP_PUTROOTFH: void; 5577 case OP_READ: READ4args opread; 5578 case OP_READDIR: READDIR4args opreaddir; 5579 case OP_READLINK: void; 5580 case OP_REMOVE: REMOVE4args opremove; 5581 case OP_RENAME: RENAME4args oprename; 5582 case OP_RENEW: RENEW4args oprenew; 5583 case OP_RESTOREFH: void; 5584 case OP_SAVEFH: void; 5585 case OP_SECINFO: SECINFO4args opsecinfo; 5586 case OP_SETATTR: SETATTR4args opsetattr; 5587 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 5588 case OP_VERIFY: VERIFY4args opverify; 5589 case OP_WRITE: WRITE4args opwrite; 5590 }; 5592 struct op { 5593 opunion ops; 5594 }; 5596 union resultdata switch (unsigned resop){ 5597 case OP_ACCESS: ACCESS4res op; 5598 case OP_CLOSE: CLOSE4res opclose; 5599 case OP_COMMIT: COMMIT4res opcommit; 5600 case OP_CREATE: CREATE4res opcreate; 5601 case OP_GETATTR: GETATTR4res opgetattr; 5602 case OP_GETFH: GETFH4res opgetfh; 5603 case OP_LINK: LINK4res oplink; 5604 case OP_LOCK: LOCK4res oplock; 5605 case OP_LOCKT: LOCKT4res oplockt; 5606 case OP_LOCKU: LOCKU4res oplocku; 5607 case OP_LOOKUP: LOOKUP4res oplookup; 5608 case OP_LOOKUPP: LOOKUPP4res oplookupp; 5609 case OP_NVERIFY: NVERIFY4res opnverify; 5610 case OP_OPEN: OPEN4res opopen; 5611 case OP_OPENATTR: OPENATTR4res opopenattr; 5612 case OP_PUTFH: PUTFH4res opputfh; 5613 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 5614 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 5615 case OP_READ: READ4res opread; 5616 case OP_READDIR: READDIR4res opreaddir; 5617 case OP_READLINK: READLINK4res opreadlink; 5618 case OP_REMOVE: REMOVE4res opremove; 5619 case OP_RENAME: RENAME4res oprename; 5620 case OP_RENEW: RENEW4res oprenew; 5621 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 5622 case OP_SAVEFH: SAVEFH4res opsavefh; 5623 case OP_SECINFO: SECINFO4res opsecinfo; 5624 case OP_SETATTR: SETATTR4res opsetattr; 5625 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 5626 case OP_VERIFY: VERIFY4res opverify; 5627 case OP_WRITE: WRITE4res opwrite; 5628 }; 5630 struct COMPOUND4args { 5631 utf8string tag; 5632 op oplist<>; 5633 }; 5635 struct COMPOUND4resok { 5636 utf8string tag; 5637 resultdata data<>; 5638 }; 5640 union COMPOUND4res switch (nfsstat4 status){ 5641 case NFS4_OK: 5642 COMPOUND4resok resok4; 5643 default: 5644 void; 5645 }; 5647 /* 5648 * Remote file service routines 5649 */ 5650 program NFS4_PROGRAM { 5651 version NFS_V4 { 5652 void 5653 NFSPROC4_NULL(void) = 0; 5655 COMPOUND4res 5656 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 5658 } = 4; 5659 } = 100003; 5661 15. Bibliography 5663 [Gray] 5664 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 5665 for Distributed File Cache Consistency," Proceedings of the Twelfth 5666 Symposium on Operating Systems Principles, p. 202-210, December 1989. 5668 [Juszczak] 5669 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 5670 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 5671 CA, June 1990, pages 53-63. Describes reply cache implementation 5672 that avoids work in the server by handling duplicate requests. More 5673 important, though listed as a side-effect, the reply cache aids in 5674 the avoidance of destructive non-idempotent operation re-application 5675 -- improving correctness. 5677 [Kazar] 5678 Kazar, Michael Leon, "Synchronization and Caching Issues in the 5679 Andrew File System," USENIX Conference Proceedings, USENIX 5680 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 5681 description of the cache consistency scheme in AFS. Contrasted with 5682 other distributed file systems. 5684 [Macklem] 5685 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 5686 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 5687 Association, Berkeley, CA, January 1991. Describes performance work 5688 in tuning the 4.3BSD Reno NFS implementation. Describes performance 5689 improvement (reduced CPU loading) through elimination of data copies. 5691 [Mogul] 5692 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 5693 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 5694 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 5695 lease-based scheme for recovering state of consistency protocol. 5697 [Nowicki] 5698 Nowicki, Bill, "Transport Issues in the Network File System," ACM 5699 SIGCOMM newsletter Computer Communication Review, April 1989. A 5700 brief description of the basis for the dynamic retransmission work. 5702 [Pawlowski] 5703 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 5704 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 5705 Conf. Proc., (1989) Description of an NFS server implementation for 5706 IBM's MVS operating system. 5708 [RFC1094] 5709 Sun Microsystems, Inc., "NFS: Network File System Protocol 5710 Specification", RFC1094, March 1989. 5712 http://www.ietf.org/rfc/rfc1094.txt 5714 [RFC1345] 5715 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 5716 Rationel Almen Planlaegning, June 1992. 5718 http://www.ietf.org/rfc/rfc1345.txt 5720 [RFC1813] 5721 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 5722 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 5724 http://www.ietf.org/rfc/rfc1813.txt 5726 [RFC1831] 5727 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 5728 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 5730 http://www.ietf.org/rfc/rfc1831.txt 5732 [RFC1832] 5733 Srinivasan, R., "XDR: External Data Representation Standard", 5734 RFC1832, Sun Microsystems, Inc., August 1995. 5736 http://www.ietf.org/rfc/rfc1832.txt 5738 [RFC1833] 5739 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 5740 Sun Microsystems, Inc., August 1995. 5742 http://www.ietf.org/rfc/rfc1833.txt 5744 [RFC2054] 5745 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 5746 Microsystems, Inc., October 1996 5748 http://www.ietf.org/rfc/rfc2054.txt 5750 [RFC2055] 5751 Callaghan, B., "WebNFS Server Specification", RFC2054, Sun 5752 Microsystems, Inc., October 1996 5754 http://www.ietf.org/rfc/rfc2055.txt 5756 [RFC2078] 5757 Linn, J., "Generic Security Service Application Program Interface, 5758 Version 2", RFC2078, OpenVision Technologies, January 1997. 5760 http://www.ietf.org/rfc/rfc2078.txt 5762 [RFC2152] 5763 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 5764 RFC2152, Apple Computer, Inc., May 1997 5766 http://www.ietf.org/rfc/rfc2152.txt 5768 [RFC2203] 5769 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 5770 RFC2203, Sun Microsystems, Inc., August 1995. 5772 http://www.ietf.org/rfc/rfc2203.txt 5774 [RFC2279] 5775 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 5776 Alis Technologies, January 1998. 5778 http://www.ietf.org/rfc/rfc2279.txt 5780 [Sandberg] 5781 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 5782 and Implementation of the Sun Network Filesystem," USENIX Conference 5783 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 5784 basic paper describing the SunOS implementation of the NFS version 2 5785 protocol, and discusses the goals, protocol specification and trade- 5786 offs. 5788 [SPNEGO] 5789 Baize, E., Pinkas, D., "The Simple and Protected GSS-API Negotiation 5790 Mechanism", draft-ietf-cat-snego-09.txt, Bull, April 1998. 5792 ftp://ftp.isi.edu/internet-drafts/draft-ietf-cat-snego-09.txt 5794 [Srinivasan] 5795 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 5796 Performance of Cache Consistency Protocols", WRL Research Report 5797 89/5, Digital Equipment Corporation Western Research Laboratory, 100 5798 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 5799 the effect of applying a Sprite-like consistency protocol applied to 5800 standard NFS. The issues of recovery in a stateful environment are 5801 covered in [Mogul]. 5803 [Unicode1] 5804 "Unicode Technical Report #8 - The Unicode Standard, Version 2.1", 5805 Unicode, Inc., The Unicode Consortium, P.O. Box 700519, San Jose, CA 5806 95710-0519 USA, September 1998 5808 http://www.unicode.org/unicode/reports/tr8.html 5810 [Unicode2] 5811 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 5812 700519, San Jose, CA 95710-0519 USA, October 1998 5814 http://www.unicode.org/unicode/standard/unsupported.html 5816 [XNFS] 5817 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 5818 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 5819 1-85912-184-5, February 1998. 5821 HTML version available: http://www.opengroup.org 5823 16. Authors and Contributors 5825 General feedback related to this document should be directed to: 5827 nfsv4-wg@sunroof.eng.sun.com 5829 or the editor. 5831 16.1. Contributors 5833 The following individuals have contributed to the document: 5835 Carl Beame, beame@bws.com, of Hummingbird Communications Ltd. 5837 16.2. Editor's Address 5839 Spencer Shepler 5840 Sun Microsystems, Inc. 5841 7808 Moonflower Drive 5842 Austin, Texas 78750 5844 Phone: +1 512-349-9376 5845 E-mail: shepler@eng.sun.com 5847 16.3. Authors' Addresses 5849 Brent Callaghan 5850 Sun Microsystems, Inc. 5851 901 San Antonio Road 5852 Palo Alto, CA 94303 5854 Phone: +1 650-786-5067 5855 E-mail: brent.callaghan@eng.sun.com 5857 Mike Eisler 5858 Sun Microsystems, Inc. 5859 5565 Wilson Road 5860 Colorado Springs, CO 80919 5862 Phone: +1 719-599-9026 5863 E-mail: mre@eng.sun.com 5865 David Robinson 5866 Sun Microsystems, Inc. 5867 901 San Antonio Road 5868 Palo Alto, CA 94303 5869 Phone: +1 650-786-5088 5870 E-mail: david.robinson@eng.sun.com 5872 Robert Thurlow 5873 Sun Microsystems, Inc. 5874 901 San Antonio Road 5875 Palo Alto, CA 94303 5877 Phone: +1 650-786-5096 5878 E-mail: robert.thurlow@eng.sun.com 5880 17. Full Copyright Statement 5882 "Copyright (C) The Internet Society (1999). All Rights Reserved. 5884 This document and translations of it may be copied and furnished to 5885 others, and derivative works that comment on or otherwise explain it 5886 or assist in its implementation may be prepared, copied, published 5887 and distributed, in whole or in part, without restriction of any 5888 kind, provided that the above copyright notice and this paragraph are 5889 included on all such copies and derivative works. However, this 5890 document itself may not be modified in any way, such as by removing 5891 the copyright notice or references to the Internet Society or other 5892 Internet organizations, except as needed for the purpose of 5893 developing Internet standards in which case the procedures for 5894 copyrights defined in the Internet Standards process must be 5895 followed, or as required to translate it into languages other than 5896 English. 5898 The limited permissions granted above are perpetual and will not be 5899 revoked by the Internet Society or its successors or assigns. 5901 This document and the information contained herein is provided on an 5902 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5903 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5904 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5905 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5906 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."