idnits 2.17.1 draft-ietf-nfsv4-02.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: ---------------------------------------------------------------------------- ** 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 6 longer pages, the longest (page 33) being 70 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 212 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 3594 has weird spacing: '...S4resok reso...' == Line 3787 has weird spacing: '...T4resok reso...' == Line 3922 has weird spacing: '..._change befo...' == Line 3923 has weird spacing: '..._change afte...' == Line 4168 has weird spacing: '...R4resok resok...' == (32 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 (October 1999) is 8960 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 8602 looks like a reference -- Missing reference section? 'RFC1813' on line 8614 looks like a reference -- Missing reference section? 'RFC1831' on line 8620 looks like a reference -- Missing reference section? 'RFC1832' on line 8626 looks like a reference -- Missing reference section? 'RFC2203' on line 8664 looks like a reference -- Missing reference section? 'RFC1833' on line 8632 looks like a reference -- Missing reference section? 'RFC2078' on line 8652 looks like a reference -- Missing reference section? 'RFC1964' on line 306 looks like a reference -- Missing reference section? 'RFC2623' on line 8676 looks like a reference -- Missing reference section? 'RFC2054' on line 8640 looks like a reference -- Missing reference section? 'RFC2055' on line 8646 looks like a reference -- Missing reference section? 'RFC2624' on line 8685 looks like a reference -- Missing reference section? 'XNFS' on line 8721 looks like a reference -- Missing reference section? '4' on line 7546 looks like a reference -- Missing reference section? 'RFC1345' on line 8608 looks like a reference -- Missing reference section? 'RFC2279' on line 8670 looks like a reference -- Missing reference section? 'RFC2152' on line 8658 looks like a reference -- Missing reference section? 'Unicode1' on line 8708 looks like a reference -- Missing reference section? 'Unicode2' on line 8715 looks like a reference -- Missing reference section? 'Gray' on line 8555 looks like a reference -- Missing reference section? 'Juszczak' on line 8560 looks like a reference -- Missing reference section? 'Kazar' on line 8569 looks like a reference -- Missing reference section? 'Macklem' on line 8576 looks like a reference -- Missing reference section? 'Mogul' on line 8706 looks like a reference -- Missing reference section? 'Nowicki' on line 8589 looks like a reference -- Missing reference section? 'Pawlowski' on line 8596 looks like a reference -- Missing reference section? 'Sandberg' on line 8691 looks like a reference -- Missing reference section? 'Srinivasan' on line 8699 looks like a reference Summary: 4 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-02.txt M. Eisler 4 D. Robinson 5 R. Thurlow 6 Sun Microsystems 7 D. Noveck 8 Network Appliance 9 C. Beame 10 Hummingbird Communications 11 October 1999 13 NFS version 4 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet- Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 Abstract 38 NFS version 4 is a distributed file system protocol which owes 39 heritage to NFS versions 2 [RFC1094] and 3 [RFC1813]. Unlike earlier 40 versions, NFS version 4 supports traditional file access while 41 integrating support for file locking and the mount protocol. In 42 addition, support for strong security (and its negotiation), compound 43 operations, and internationlization have been added. Of course, 45 Draft Protocol Specification NFS version 4 October 1999 47 attention has been applied to making NFS version 4 operate well in an 48 Internet environment. 50 Copyright 52 Copyright (C) The Internet Society (1999). All Rights Reserved. 54 Key Words 56 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 57 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 58 document are to be interpreted as described in RFC 2119. 60 Draft Protocol Specification NFS version 4 October 1999 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2. RPC and Security Flavor . . . . . . . . . . . . . . . . . . 8 66 2.1. Ports and Transports . . . . . . . . . . . . . . . . . . . 8 67 2.2. Security Flavors . . . . . . . . . . . . . . . . . . . . . 8 68 2.2.1. Security mechanisms for NFS version 4 . . . . . . . . . 8 69 2.2.1.1. Kerberos V5 as security triple . . . . . . . . . . . . 8 70 2.2.1.2. . . . . . . . . . . . . . . 9 71 2.3. Security Negotiation . . . . . . . . . . . . . . . . . . . 9 72 2.3.1. Security Error . . . . . . . . . . . . . . . . . . . . 10 73 2.3.2. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 10 74 3. File handles . . . . . . . . . . . . . . . . . . . . . . . 11 75 3.1. Obtaining the First File Handle . . . . . . . . . . . . 11 76 3.1.1. Root File Handle . . . . . . . . . . . . . . . . . . . 11 77 3.1.2. Public File Handle . . . . . . . . . . . . . . . . . . 12 78 3.2. File Handle Types . . . . . . . . . . . . . . . . . . . 12 79 3.2.1. General Properties of a File Handle . . . . . . . . . 12 80 3.2.2. Persistent File Handle . . . . . . . . . . . . . . . . 13 81 3.2.3. Volatile File Handle . . . . . . . . . . . . . . . . . 13 82 3.2.4. One Method of Constructing a Volatile File Handle . . 15 83 3.3. Client Recovery from File Handle Expiration . . . . . . 15 84 4. Basic Data Types . . . . . . . . . . . . . . . . . . . . . 17 85 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 19 86 5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 20 87 5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 20 88 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 20 89 5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 22 90 5.5. Recommended Attributes - Definitions . . . . . . . . . . 25 91 5.6. Interpreting owner and owner_group . . . . . . . . . . . 30 92 5.7. Access Control Lists . . . . . . . . . . . . . . . . . . 30 93 5.7.1. ACE type . . . . . . . . . . . . . . . . . . . . . . . 31 94 5.7.2. ACE flag . . . . . . . . . . . . . . . . . . . . . . . 31 95 5.7.3. ACE Access Mask . . . . . . . . . . . . . . . . . . . 33 96 5.7.4. ACE who . . . . . . . . . . . . . . . . . . . . . . . 33 97 6. Filesystem Migration and Replication . . . . . . . . . . . 35 98 6.1. Replication . . . . . . . . . . . . . . . . . . . . . . 35 99 6.2. Migration . . . . . . . . . . . . . . . . . . . . . . . 35 100 6.3. Interpretation of the fs_locations Attribute . . . . . . 36 101 6.4. Filehandle Recovery for Migration or Replication . . . . 37 102 7. NFS Server Namespace . . . . . . . . . . . . . . . . . . . 38 103 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 38 104 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 38 105 7.3. Server Pseudo File-System . . . . . . . . . . . . . . . 39 106 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 39 107 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 39 108 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 40 109 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 40 111 Draft Protocol Specification NFS version 4 October 1999 113 7.8. Security Policy and Namespace Presentation . . . . . . . 41 114 7.9. Summary . . . . . . . . . . . . . . . . . . . . . . . . 41 115 8. File Locking . . . . . . . . . . . . . . . . . . . . . . . 42 116 8.1. Definitions . . . . . . . . . . . . . . . . . . . . . . 42 117 8.2. Locking . . . . . . . . . . . . . . . . . . . . . . . . 43 118 8.2.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 43 119 8.2.2. nfs_lockowner and stateid Definition . . . . . . . . . 45 120 8.2.3. Use of the stateid . . . . . . . . . . . . . . . . . . 45 121 8.2.4. Sequencing of Lock Requests . . . . . . . . . . . . . 46 122 8.3. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 46 123 8.4. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 47 124 8.5. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 47 125 8.5.1. Client Failure and Recovery . . . . . . . . . . . . . 47 126 8.5.2. Server Failure and Recovery . . . . . . . . . . . . . 48 127 8.5.3. Network Partitions and Recovery . . . . . . . . . . . 48 128 8.6. Server Revocation of Locks . . . . . . . . . . . . . . . 49 129 8.7. Share Reservations . . . . . . . . . . . . . . . . . . . 50 130 8.8. OPEN/CLOSE Procedures . . . . . . . . . . . . . . . . . 51 131 9. Client-Side Caching . . . . . . . . . . . . . . . . . . . 52 132 9.1. Performance Challenges for Client-Side Caching . . . . . 52 133 9.2. Proxy Caching . . . . . . . . . . . . . . . . . . . . . 53 134 9.3. Delegation and Callbacks . . . . . . . . . . . . . . . . 54 135 9.3.1. Delegation Recovery . . . . . . . . . . . . . . . . . 55 136 9.4. Data Caching . . . . . . . . . . . . . . . . . . . . . . 57 137 9.4.1. Data Caching and OPENs . . . . . . . . . . . . . . . . 57 138 9.4.2. Data Caching and File Locking . . . . . . . . . . . . 58 139 9.4.3. Data Caching and Mandatory File Locking . . . . . . . 59 140 9.4.4. Data Caching and File Identity . . . . . . . . . . . . 60 141 9.5. Open Delegation . . . . . . . . . . . . . . . . . . . . 61 142 9.5.1. Open Delegation and Data Caching . . . . . . . . . . . 63 143 9.5.2. Open Delegation and File Locks . . . . . . . . . . . . 64 144 9.5.3. Recall of Open Delegation . . . . . . . . . . . . . . 64 145 9.5.4. Delegation Revocation . . . . . . . . . . . . . . . . 67 146 9.6. Data Caching and Revocation . . . . . . . . . . . . . . 67 147 9.6.1. Revocation Recovery for Write Open Delegation . . . . 67 148 9.7. Attribute Caching . . . . . . . . . . . . . . . . . . . 68 149 9.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 69 150 9.9. Directory Caching . . . . . . . . . . . . . . . . . . . 70 151 10. Defined Error Numbers . . . . . . . . . . . . . . . . . . 72 152 11. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 77 153 11.1. Compound Procedure . . . . . . . . . . . . . . . . . . 77 154 11.2. Evaluation of a Compound Request . . . . . . . . . . . 77 155 12. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 79 156 12.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 79 157 12.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 80 158 12.2.1. Operation 2: ACCESS - Check Access Rights . . . . . . 82 159 12.2.2. Operation 3: CLOSE - Close File . . . . . . . . . . . 86 160 12.2.3. Operation 4: COMMIT - Commit Cached Data . . . . . . 88 162 Draft Protocol Specification NFS version 4 October 1999 164 12.2.4. Operation 5: CREATE - Create a Non-Regular File Object 91 165 12.2.5. Operation 6: DELEGPURGE - Purge Delegations Awaiting 166 Recovery . . . . . . . . . . . . . . . . . . . . . . 95 167 12.2.6. Operation 7: DELEGRETURN - Return Delegation . . . . 96 168 12.2.7. Operation 8: GETATTR - Get Attributes . . . . . . . . 97 169 12.2.8. Operation 9: GETFH - Get Current Filehandle . . . . . 99 170 12.2.9. Operation 10: LINK - Create Link to a File . . . . . 101 171 12.2.10. Operation 11: LOCK - Create Lock . . . . . . . . . . 103 172 12.2.11. Operation 12: LOCKT - Test For Lock . . . . . . . . 105 173 12.2.12. Operation 13: LOCKU - Unlock File . . . . . . . . . 107 174 12.2.13. Operation 14: LOOKUP - Lookup Filename . . . . . . . 109 175 12.2.14. Operation 15: LOOKUPP - Lookup Parent Directory . . 112 176 12.2.15. Operation 16: NVERIFY - Verify Difference in 177 Attributes . . . . . . . . . . . . . . . . . . . . . 114 178 12.2.16. Operation 17: OPEN - Open a Regular File . . . . . . 116 179 12.2.17. Operation 18: OPENATTR - Open Named Attribute 180 Directory . . . . . . . . . . . . . . . . . . . . . 124 181 12.2.18. Operation 19: PUTFH - Set Current Filehandle . . . . 126 182 12.2.19. Operation 20: PUTPUBFH - Set Public Filehandle . . . 128 183 12.2.20. Operation 21: PUTROOTFH - Set Root Filehandle . . . 129 184 12.2.21. Operation 22: READ - Read from File . . . . . . . . 130 185 12.2.22. Operation 23: READDIR - Read Directory . . . . . . . 133 186 12.2.23. Operation 24: READLINK - Read Symbolic Link . . . . 137 187 12.2.24. Operation 25: REMOVE - Remove Filesystem Object . . 139 188 12.2.25. Operation 26: RENAME - Rename Directory Entry . . . 141 189 12.2.26. Operation 27: RENEW - Renew a Lease . . . . . . . . 144 190 12.2.27. Operation 28: RESTOREFH - Restore Saved Filehandle . 145 191 12.2.28. Operation 29: SAVEFH - Save Current Filehandle . . . 147 192 12.2.29. Operation 30: SECINFO - Obtain Available Security . 149 193 12.2.30. Operation 31: SETATTR - Set Attributes . . . . . . . 151 194 12.2.31. Operation 32: SETCLIENTID - Negotiated Clientid . . 154 195 12.2.32. Operation 33: VERIFY - Verify Same Attributes . . . 156 196 12.2.33. Operation 34: WRITE - Write to File . . . . . . . . 158 197 13. NFS Version 4 Callback Procedures . . . . . . . . . . . . 163 198 13.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 163 199 13.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 164 200 13.2.1. Procedure 2: CB_GETATTR - Get Attributes . . . . . . 166 201 13.2.2. Procedure 3: CB_RECALL - Recall an Open Delegation . 168 202 14. Locking notes . . . . . . . . . . . . . . . . . . . . . . 170 203 14.1. Short and long leases . . . . . . . . . . . . . . . . . 170 204 14.2. Clocks and leases . . . . . . . . . . . . . . . . . . . 170 205 14.3. Locks and lease times . . . . . . . . . . . . . . . . . 170 206 14.4. Locking of directories and other meta-files . . . . . . 171 207 14.5. Proxy servers and leases . . . . . . . . . . . . . . . 171 208 14.6. Locking and the new latency . . . . . . . . . . . . . . 171 209 15. Internationalization . . . . . . . . . . . . . . . . . . 172 210 15.1. Universal Versus Local Character Sets . . . . . . . . . 172 211 15.2. Overview of Universal Character Set Standards . . . . . 173 213 Draft Protocol Specification NFS version 4 October 1999 215 15.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 174 216 15.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 175 217 16. Security Considerations . . . . . . . . . . . . . . . . . 176 218 17. NFS Version 4 RPC definition file . . . . . . . . . . . . 177 219 18. Bibliography . . . . . . . . . . . . . . . . . . . . . . 206 220 19. Authors and Contributors . . . . . . . . . . . . . . . . 210 221 19.1. Editor's Address . . . . . . . . . . . . . . . . . . . 210 222 19.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 210 223 20. Full Copyright Statement . . . . . . . . . . . . . . . . 212 225 Draft Protocol Specification NFS version 4 October 1999 227 1. Introduction 229 NFS version 4 is a further revision of the NFS protocol defined 230 already by versions 2 [RFC1094] and 3 [RFC1813]. It retains the 231 essential characteristics of previous versions: design for easy 232 recovery, independent of transport protocols, operating systems and 233 filesystems, simplicity, and good performance. The NFS version 4 234 revision has the following goals: 236 o Improved access and good performance on the Internet. 238 The protocol is designed to transit firewalls easily, perform 239 well where latency is high and bandwidth is low, and scale to 240 very large numbers of clients per server. 242 o Strong security with negotiation built into the protocol. 244 The protocol builds on the work of the ONCRPC working group in 245 supporting the RPCSEC_GSS protocol. Additionally NFS version 4 246 provides a mechanism to allow clients and servers to negotiate 247 security and require clients and servers to support a minimal 248 set of security schemes. 250 o Good cross-platform interoperability. 252 The protocol features a filesystem model that provides a useful, 253 common set of features that does not unduly favor one filesystem 254 or operating system over another. 256 o Designed for protocol extensions. 258 The protocol is designed to accept standard extensions that do 259 not compromise backward compatibility. 261 Draft Protocol Specification NFS version 4 October 1999 263 2. RPC and Security Flavor 265 The NFS version 4 protocol is a Remote Procedure Call (RPC) 266 application that uses RPC version 2 and the corresponding eXternal 267 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 268 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 269 the mechanism to deliver stronger security to NFS version 4. 271 2.1. Ports and Transports 273 Historically, NFS version 2 and version 3 servers have resided on 274 UDP/TCP port 2049. Port 2049 is a IANA registered port number for NFS 275 and therefore will continue to be used for NFS version 4. Using the 276 well known port for NFS services means the NFS client will not need 277 to use the RPC binding protocols as described in [RFC1833]; this will 278 allow NFS to transit firewalls. 280 The NFS server SHOULD offer its RPC service via TCP as the primary 281 transport. The server SHOULD also provide UDP for RPC service. The 282 NFS client SHOULD also have a preference for TCP usage but may supply 283 a mechanism to override TCP in favor of UDP as the RPC transport. 285 2.2. Security Flavors 287 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 288 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 289 additional security flavor of RPCSEC_GSS has been introduced which 290 uses the functionality of GSS-API [RFC2078]. This allows for the use 291 of varying security mechanisms by the RPC layer without the 292 additional implementation overhead of adding RPC security flavors. 293 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 294 enable the mandatory security mechanism. The flavors AUTH_NONE, 295 AUTH_SYS, and AUTH_DH MAY be implemented as well. 297 2.2.1. Security mechanisms for NFS version 4 299 The use of RPCSEC_GSS requires selection of: mechanism, quality of 300 protection, and service (authentication, integrity, privacy). The 301 remainder of this document will refer to these three parameters of 302 the RPCSEC_GSS security as the security triple. 304 2.2.1.1. Kerberos V5 as security triple 306 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 307 implemented and provide the following security triples. 309 columns: 311 Draft Protocol Specification NFS version 4 October 1999 313 1 == number of pseudo flavor 314 2 == name of pseudo flavor 315 3 == mechanism's OID 316 4 == mechanism's algorithm(s) 317 5 == RPCSEC_GSS service 319 1 2 3 4 5 320 ----------------------------------------------------------------------- 321 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 322 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 323 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 324 for integrity, 325 and 56 bit DES 326 for privacy. 328 Note that the pseudo flavor is presented here as a mapping aid to the 329 implementor. Because this NFS protocol includes a method to 330 negotiate security and it understands the GSS-API mechanism, the 331 pseudo flavor is not needed. The pseudo flavor is needed for NFS 332 version 3 since the security negotiation is done via the MOUNT 333 protocol. 335 For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please 336 see [RFC2623]. 338 2.2.1.2. 340 Another GSS-API mechanism will need to be specified here 341 along with the corresponding security triple(s). 343 2.3. Security Negotiation 345 With the NFS version 4 server potentially offering multiple security 346 mechanisms, the client will need a way to determine or negotiate 347 which mechanism is to be used for its communication with the server. 348 The NFS server may have multiple points within its file system name 349 space that are available for use by NFS clients. In turn the NFS 350 server may be configured such that each of these entry points may 351 have different or multiple security mechanisms in use. 353 The security negotiation between client and server must be done with 354 a secure channel to eliminate the possibility of a third party 355 intercepting the negotiation sequence and forcing the client and 356 server to choose a lower level of security than required/desired. 358 Draft Protocol Specification NFS version 4 October 1999 360 2.3.1. Security Error 362 Based on the assumption that each NFS version 4 client and server 363 must support a minimum set of security (i.e. Kerberos-V5 under 364 RPCSEC_GSS, ), the NFS client will start its 365 communication with the server with one of the minimal security 366 triples. During communication with the server, the client may 367 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 368 server to notify the client that the security triple currently being 369 used is not appropriate for access to the server's file system 370 resources. The client is then responsible for determining what 371 security triples are available at the server and choose one which is 372 appropriate for the client. 374 2.3.2. SECINFO 376 The new procedure SECINFO (see SECINFO procedure definition) will 377 allow the client to determine, on a per filehandle basis, what 378 security triple is to be used for server access. In general, the 379 client will not have to use the SECINFO procedure except during 380 initial communication with the server or when the client crosses 381 policy boundaries at the server. It could happen that the server's 382 policies change during the client's interaction therefore forcing the 383 client to negotiate a new security triple. 385 Draft Protocol Specification NFS version 4 October 1999 387 3. File handles 389 The file handle in the NFS protocol is a per server unique identifier 390 for a file system object. The contents of the file handle are opaque 391 to the client. Therefore, the server is responsible for translating 392 the file handle to an internal representation of the file system 393 object. Since the file handle is the client's reference to an object 394 and the client may cache this reference, the server should not reuse 395 a file handle for another file system object. If the server needs to 396 reuse a file handle value, the time elapsed before reuse SHOULD be 397 large enough that it is likely the client no longer has a cached copy 398 of the reused file handle value. 400 3.1. Obtaining the First File Handle 402 The procedures of the NFS protocol are defined in terms of one or 403 more file handles. Therefore, the client needs a file handle to 404 initiate communication with the server. With NFS version 2 [RFC1094] 405 and NFS version 3 [RFC1813], there exists an ancillary protocol to 406 obtain this first file handle. The MOUNT protocol, RPC program 407 number 100005, provides the mechanism of translating a string based 408 file system path name to a file handle which can then be used by the 409 NFS protocols. 411 The MOUNT protocol has deficiencies in the area of security and use 412 via firewalls. This is one reason that the use of the public file 413 handle was introduced [RFC2054] [RFC2055]. With the use of public 414 file handle in combination with the LOOKUP procedure in NFS version 2 415 and 3, it has been demonstrated that the MOUNT protocol is 416 unnecessary for viable interaction between NFS client and server. 418 Therefore, NFS version 4 will not use an ancillary protocol for 419 translation from string based path names to a file handle. Two 420 special file handles will be used as starting points for the NFS 421 client. 423 3.1.1. Root File Handle 425 The first of the special file handles is the ROOT file handle. The 426 ROOT file handle is the "conceptual" root of the file system name 427 space at the NFS server. The client uses or starts with the ROOT 428 file handle by employing the PUTROOTFH procedure. The PUTROOTFH 429 procedure instructs the server to set the "current" file handle to 430 the ROOT of the server's file tree. Once this PUTROOTFH procedure is 431 used, the client can then traverse the entirety of the server's file 432 tree with the LOOKUP procedure. A complete discussion of the server 433 name space is in section 7, "NFS Server Name Space". 435 Draft Protocol Specification NFS version 4 October 1999 437 3.1.2. Public File Handle 439 The second special file handle is the PUBLIC file handle. Unlike the 440 ROOT file handle, the PUBLIC file handle may be bound or represent an 441 arbitrary file system object at the server. The server is 442 responsible for this binding. It may be that the PUBLIC file handle 443 and the ROOT file handle refer to the same file system object. 444 However, it is up to the administrative software at the server and 445 the policies of the server administrator to define the binding of the 446 PUBLIC file handle and server file system object. The client may not 447 make any assumptions about this binding. 449 3.2. File Handle Types 451 In NFS version 2 and 3, there was one type of file handle with a 452 single set of semantics. NFS version 4 introduces a new type of file 453 handle in an attempt to accommodate certain server environments. The 454 first type of file handle is 'persistent'. The semantics of a 455 persistent file handle are the same as the file handles of NFS 456 version 2 and 3. The second or new type of file handle is the 457 'volatile' file handle. 459 The volatile file handle type is being introduced to address server 460 functionality or implementation issues which prevent correct or 461 feasible implementation of a persistent file handle. Some server 462 environments do not provide a file system level invariant that can be 463 used to construct a persistent file handle. The underlying server 464 file system may not provide the invariant or the server's file system 465 APIs may not provide access to the needed invariant. Volatile file 466 handles may ease the implementation of server functionality such as 467 hierarchical storage management or file system reorganization or 468 migration. However, the volatile file handle increases the 469 implementation burden for the client but this increased burden is 470 deemed acceptable based on the overall gains achieved by the 471 protocol. 473 Since the client will have different paths of logic to handle 474 persistent and volatile file handles, a file attribute is defined 475 which may be used by the client to determine the file handle types 476 being returned by the server. 478 3.2.1. General Properties of a File Handle 480 The file handle contains all the information the server needs to 481 distinguish an individual file. To the client, the file handle is 482 opaque. The client stores file handles for use in a later request and 484 Draft Protocol Specification NFS version 4 October 1999 486 can compare two file handles from the same server for equality by 487 doing a byte-by-byte comparison, but MUST NOT otherwise interpret the 488 contents of file handles. If two file handles from the same server 489 are equal, they MUST refer to the same file, but if they are not 490 equal, no conclusions can be drawn. Servers SHOULD try to maintain a 491 one-to-one correspondence between file handles and files but this is 492 not required. Clients MUST only use file handle comparisons only to 493 improve performance, not for correct behavior. 495 As an example, in the case that two different path names when 496 traversed at the server terminate at the same file system object, the 497 server SHOULD return the same file handle for each path. This can 498 occur if a hard link is used to create two file names which refer to 499 the same underlying file object and associated data. For example, if 500 paths /a/b/c and /a/d/c refer to the same file, the server SHOULD 501 return the same file handle for both path names traversals. 503 3.2.2. Persistent File Handle 505 A persistent file handle is defined as having a persistent value for 506 the lifetime of the file system object to which it refers. Once the 507 server creates the file handle for a file system object, the server 508 MUST return the same file handle for the object for the lifetime of 509 the object. If the server restarts or reboots, or the filesystem is 510 migrated, the NFS server must honor and present the same file handle 511 value as it did in the server's previous instantiation. 513 The persistent file handle will be become stale or invalid when the 514 file system object is removed. When the server is presented with a 515 persistent file handle that refers to a deleted object, it MUST 516 return an error of NFS4ERR_STALE. A file handle may become stale 517 when the file system containing the object is no longer available. 518 The file system may become unavailable if it exists on removable 519 media and the media is no longer available at the server or the file 520 system in whole has been destroyed or the file system has simply been 521 removed from the server's name space (i.e. unmounted in a Unix 522 environment). 524 3.2.3. Volatile File Handle 526 A volatile file handle does not share the same longevity attributes 527 of the persistent file handle. The server may determine that a 528 volatile file handle is no longer valid at many different points in 529 time. If the server can definitively determine that a volatile file 530 handle refers to an object that has been removed, the server should 531 return NFS4ERR_STALE to the client (as is the case for persistent 533 Draft Protocol Specification NFS version 4 October 1999 535 file handles). In all other cases where the server determines that a 536 volatile file handle can no longer be used, it should return an error 537 of NFS4ERR_EXPIRED. 539 The following table shows the most common points at which a volatile 540 file handle may expire. This table represents the view from the 541 client's perspective and as such provides columns for when the file 542 may be open or closed by the client. 544 Server Provides Persistent or Volatile File Handle 545 File Open File Closed 546 ___________________________________________________________________ 547 Restart of Server (note 4) P / V P / V 548 Filesystem Migration (note 5) P / V P / V 549 SHARE/LOCK recovery P / V N/A (note 1) 550 Client RENAMEs object P / V P / V 551 Client RENAMEs path to object P / V P / V 552 Other client RENAMEs object P / V P / V 553 Other client RENAMEs path to object P / V P / V 554 Client REMOVEs object P / V (note 2) P / V 555 Other client REMOVEs object P / V N/A (note 3) 557 Note 1 558 If the file is not open, persistence of the file handle is not 559 applicable for the recovery of SHARE/LOCK. 561 Note 2 562 With NFS version 2 and 3, when the client removes a file it has 563 open it follows the convention of RENAMEing the file to '.nfsXXXX' 564 until the file is closed. At this point the REMOVE is done at the 565 server. 567 If this same model is used for v4 then this entry will be 568 'N/A'. 570 Note 3 571 If the file is not open by the client, then it should not expect 572 any cached file handle to be valid. 574 Note 4 575 The restart of the NFS server signifies when the operating system 576 or NFS software is (re)started. This also includes High 577 Availability configurations where a separate operating system 578 instantiation acquires ownership of the file system resources and 579 network resources (i.e. disks and IP addresses). 581 Draft Protocol Specification NFS version 4 October 1999 583 Note 5 584 Filesystem migration may occur in response to an unresponsive 585 server or when the current server indicates that a filesystem has 586 moved by returning NFS4ERR_MOVED. In both cases, the attribute 587 fs_locations designates the new server location for the filesystem. 589 3.2.4. One Method of Constructing a Volatile File Handle 591 As mentioned, in some instances a file handle is stale (no longer 592 valid, perhaps because the file was removed from the server), or it 593 is expired (the underlying file is valid, but since the file handle 594 is volatile, it may have expired). Thus the server needs to be able 595 to return NFS4ERR_STALE in the former case, and NFS4ERR_FHEXPIRED in 596 the latter case. This can be done by careful construction of the 597 volatile file handle. One possible implementation follows. 599 A volatile file handle, while opaque to the client could contain: 601 [volatile bit = 1 | server boot time | slot | generation number] 603 o slot is an index in the server volatile file handle table 605 o generation number is the generation number for the table 606 entry/slot 608 If the server boot time is less than the current server boot time, 609 return NFS4ERR_FHEXPIRED. If slot is out of range, return 610 NFS4ERR_BADHANDLE. If the generation number does not match, return 611 NFS4ERR_BADHANDLE. 613 When the server reboots, the table is gone (it is volatile). 615 If volatile bit is 0, then it is a persistent file handle with a 616 different structure following it. 618 3.3. Client Recovery from File Handle Expiration 620 With the introduction of the volatile file handle, the client must 621 take on additional responsibility so that it may prepare itself to 622 recover from the expiration of a volatile file handle. If the server 623 returns persistent file handles, the client does not need these 624 additional steps. 626 For volatile file handles, most commonly the client will need to 627 store the component names leading up to and including the file system 629 Draft Protocol Specification NFS version 4 October 1999 631 object in question. With these names, the client should be able to 632 recover by finding a file handle in the name space that is still 633 available or by starting at the root of the server's file system name 634 space. 636 If the expired file handle refers to an object that has been removed 637 from the file system, obviously the client will not be able to 638 recover from the expired file handle. 640 It is also possible that the expired file handle refers to a file 641 that has been renamed. If the file was renamed by another client, 642 again it is possible that the original client will not be able to 643 recover. However, in the case that the client itself is renaming the 644 file and the file is open, it is possible that the client may be able 645 to recover. The client can determine the new path name based on the 646 processing of the rename request. The client can then regenerate the 647 new file handle based on the new path name. The client could also 648 use the compound operation mechanism to construct a set of operations 649 like: 650 RENAME A B 651 LOOKUP B 652 GETFH 654 Draft Protocol Specification NFS version 4 October 1999 656 4. Basic Data Types 658 Arguments and results from operations will be described in terms of 659 basic XDR types defined in [RFC1832]. The following data types will 660 be defined in terms of basic XDR types: 662 filehandle: opaque <128> 664 An NFS version 4 filehandle. A filehandle with zero length is 665 recognized as a "public" filehandle. 667 utf8string: opaque <> 669 A counted array of octets that contains a UTF-8 string. 671 Note: Section 11, Internationalization, covers the rational of 672 using UTF-8. 674 bitmap: uint32 <> 676 A counted array of 32 bit integers used to contain bit values. 677 The position of the integer in the array that contains bit n can 678 be computed from the expression (n / 32) and its bit within that 679 integer is (n mod 32). 681 0 1 682 +-----------+-----------+-----------+-- 683 | count | 31 .. 0 | 63 .. 32 | 684 +-----------+-----------+-----------+-- 686 createverf: opaque<8> 688 Verify used for exclusive create semantics 690 nfstime4 691 struct nfstime4 { 692 int64_t seconds; 693 uint32_t nseconds; 694 } 696 The nfstime4 structure gives the number of seconds and 697 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 698 Universal Time (UTC). Values greater than zero for the seconds 699 field denote dates after the 0 hour January 1, 1970. Values 700 less than zero for the seconds field denote dates before the 0 701 hour January 1, 1970. In both cases, the nseconds field is to 702 be added to the seconds field for the final time representation. 703 For example, if the time to be represented is one-half second 705 Draft Protocol Specification NFS version 4 October 1999 707 before 0 hour January 1, 1970, the seconds field would have a 708 value of negative one (-1) and the nseconds fields would have a 709 value of one-half second (500000000). Values greater than 710 999,999,999 for nseconds are considered invalid. 712 This data type is used to pass time and date information. A 713 server converts to and from local time when processing time 714 values, preserving as much accuracy as possible. If the 715 precision of timestamps stored for a file system object is less 716 than defined, loss of precision can occur. An adjunct time 717 maintenance protocol is recommended to reduce client and server 718 time skew. 720 specdata4 721 struct specdata4 { 722 uint32_t specdata1; 723 uint32_t specdata2; 724 } 726 This data type represents additional information for the device 727 file types NFCHR and NFBLK. 729 Draft Protocol Specification NFS version 4 October 1999 731 5. File Attributes 733 To meet the NFS Version 4 requirements of extensibility and increased 734 interoperability with non-Unix platforms, attributes must be handled 735 in a more flexible manner. The NFS Version 3 fattr3 structure 736 contained a fixed list of attributes that not all clients and servers 737 are able to support or care about, which cannot be extended as new 738 needs arise, and which provides no way to indicate non-support. With 739 NFS Version 4, the client will be able to ask what attributes the 740 server supports, and will be able to request only those attributes in 741 which it is interested. 743 To this end, attributes will be divided into three groups: mandatory, 744 recommended and named. Both mandatory and recommended attributes are 745 supported in the NFS V4 protocol by a specific and well-defined 746 encoding, and are identified by number. They are requested by 747 setting a bit in the bit vector sent in the GETATTR request; the 748 server response includes a bit vector to list what attributes were 749 returned in response. New mandatory or recommended attributes may be 750 added to the NFS protocol between revisions by publishing a 751 standards-track RFC which allocates a new attribute number value and 752 defines the encoding for the attribute. 754 Named attributes are accessed by the new OPENATTR operation, which 755 accesses a hidden directory of attributes associated with a 756 filesystem object. OPENATTR takes a filehandle for the object and 757 returns the filehandle for the attribute hierarchy, which is a 758 directory object accessible by LOOKUP or READDIR, and which contains 759 files whose names represent the named attributes and whose data bytes 760 are the value of the attribute. For example: 762 LOOKUP "foo" ; look up file 763 GETATTR attrbits 764 OPENATTR ; access foo's named attributes 765 LOOKUP "x11icon" ; look up specific attribute 766 READ 0,4096 ; read stream of bytes 768 Named attributes are intended primarily for data needed by 769 applications rather than by an NFS client implementation per se; NFS 770 implementors are strongly encouraged to define their new attributes 771 as recommended attributes by bringing them to the working group. 773 The set of attributes which are classified as mandatory is 774 deliberately small, since servers must do whatever it takes to 775 support them. The recommended attributes may be unsupported, though 776 a server should support as many as it can. Attributes are deemed 778 Draft Protocol Specification NFS version 4 October 1999 780 mandatory if the data is both needed by a large number of clients and 781 is not otherwise reasonably computable by the client when support is 782 not provided on the server. 784 5.1. Mandatory Attributes 786 These MUST be supported by every NFS Version 4 client and server in 787 order to ensure a minimum level of interoperability. The server must 788 store and return these attributes, and the client must be able to 789 function with an attribute set limited to these attributes, though 790 some operations may be impaired or limited in some ways in this case. 791 A client may ask for any of these attributes to be returned by 792 setting a bit in the GETATTR request, and the server must return 793 their value. 795 5.2. Recommended Attributes 797 These attributes are understood well enough to warrant support in the 798 NFS Version 4 protocol, though they may not be supported on all 799 clients and servers. A client may ask for any of these attributes to 800 be returned by setting a bit in the GETATTR request, but must be able 801 to deal with not receiving them. A client may ask for the set of 802 attributes the server supports and should not request attributes the 803 server does not support. A server should be tolerant of requests for 804 unsupported attributes, and simply not return them, rather than 805 considering the request an error. It is expected that servers will 806 support all attributes they comfortably can, and only fail to support 807 attributes which are difficult to support in their operating 808 environments. A server should provide attributes whenever they don't 809 have to "tell lies" to the client. For example, a file modification 810 time should be either an accurate time or should not be supported by 811 the server. This will not always be comfortable to clients but it 812 seems that the client has a better ability to fabricate or construct 813 an attribute or do without. 815 Most attributes from NFS V3's FSINFO, FSSTAT and PATHCONF procedures 816 have been added as recommended attributes, so that filesystem info 817 may be collected via the filehandle of any object the filesystem. 818 This renders those procedures unnecessary in NFS V4. 820 5.3. Named Attributes 822 These attributes are not supported by direct encoding in the NFS 823 Version 4 protocol but are accessed by string names rather than 824 numbers and correspond to an uninterpreted stream of bytes which are 826 Draft Protocol Specification NFS version 4 October 1999 828 stored with the filesystem object. The namespace for these 829 attributes may be accessed by using the OPENATTR operation to get a 830 filehandle for a virtual "attribute directory" and using READDIR and 831 LOOKUP operations on this filehandle. Named attributes may then be 832 examined or changed by normal READ and WRITE and CREATE operations on 833 the filehandles returned from READDIR and LOOKUP. Named attributes 834 may have attributes, for example, a security label may have access 835 control information in its own right. 837 It is recommended that servers support arbitrary named attributes. A 838 client should not depend on the ability to store any named attributes 839 in the server's filesystem. If a server does support named 840 attributes, a client which is also able to handle them should be able 841 to copy a file's data and meta-data with complete transparency from 842 one location to another; this would imply that there should be no 843 attribute names which will be considered illegal by the server. 845 Names of attributes will not be controlled by a standards body. 846 However, vendors and application writers are encouraged to register 847 attribute names and the interpretation and semantics of the stream of 848 bytes via informational RFC so that vendors may interoperate where 849 common interests exist. 851 Draft Protocol Specification NFS version 4 October 1999 853 5.4. Mandatory Attributes - Definitions 855 Name # DataType Access Description 856 ___________________________________________________________________ 857 supp_attr 0 bitmap READ 858 The bit vector which 859 would retrieve all 860 mandatory and 861 recommended attributes 862 which may be requested 863 for this object. 865 The client must ask 866 this question to 867 request correct 868 attributes. 870 object_type 1 nfs4_ftype READ 871 The type of the object 872 (file, directory, 873 symlink) 875 The client cannot 876 handle object 877 correctly without 878 type. 880 persistent_fh 2 boolean READ 881 Is the filehandle for 882 this object 883 persistent? 885 Server should know if 886 the filehandles being 887 provided are 888 persistent or not. If 889 the server is not able 890 to make this 891 determination, then it 892 can choose volatile or 893 non-persistent. 895 Draft Protocol Specification NFS version 4 October 1999 897 change 3 uint64 READ 898 A value created by the 899 server that the client 900 can use to determine 901 if a file data, 902 directory contents or 903 attributes have been 904 modified. The server 905 can just return the 906 file mtime in this 907 field though if a more 908 precise value exists 909 then it can be 910 substituted, for 911 instance, a sequence 912 number. 914 Necessary for any 915 useful caching, likely 916 to be available. 918 object_size 4 uint64 R/W 919 The size of the object 920 in bytes. 922 Could be very 923 expensive to derive, 924 likely to be 925 available. 927 link_support 5 boolean READ 928 Does the object's 929 filesystem supports 930 hard links? 932 Server can easily 933 determine if links are 934 supported. 936 symlink_support 6 boolean READ 937 Does the object's 938 filesystem supports 939 symbolic links? 941 Server can easily 942 determine if links are 943 supported. 945 named_attr 7 boolean READ 946 Does this object have 947 named attributes? 949 Draft Protocol Specification NFS version 4 October 1999 951 fsid 8 fsid4 READ 952 Unique filesystem 953 identifier for the 954 filesystem holding 955 this object. fsid 956 contains major and 957 minor components each 958 of which are uint64. 960 unique_handles 9 boolean READ 961 Are two distinct 962 filehandles guaranteed 963 to refer to two 964 different file system 965 objects? 967 lease_time 10 uint32 READ 968 Duration of leases at 969 server in seconds. 971 rdattr_error 11 enum READ 972 Error returned from 973 getattr during 974 readdir. 976 Draft Protocol Specification NFS version 4 October 1999 978 5.5. Recommended Attributes - Definitions 980 Name # Data Type Access Description 981 _____________________________________________________________________ 982 ACL 12 nfsace4<> R/W 983 The access control 984 list for the object. 985 [The nature and 986 format of ACLs is 987 still to be 988 determined.] 990 aclsupport 13 uint32 READ 991 Indicates what ACLs 992 are supported on the 993 current filesystem. 995 archive 14 boolean R/W 996 Whether or not this 997 file has been 998 archived since the 999 time of last 1000 modification 1001 (deprecated in favor 1002 of backup_time). 1004 cansettime 15 boolean READ 1005 Whether or not this 1006 object's filesystem 1007 can fill in the times 1008 on a SETATTR request 1009 without an explicit 1010 time. 1012 case_insensitive 16 boolean READ 1013 Are filename 1014 comparisons on this 1015 filesystem case 1016 insensitive? 1018 case_preserving 17 boolean READ 1019 Is filename case on 1020 this filesystem 1021 preserved? 1023 chown_restricted 18 boolean READ 1024 Will a request to 1025 change ownership be 1026 honored? 1028 filehandle 19 nfs4_fh READ 1029 The filehandle of 1030 this object 1031 (primarily for 1032 readdir requests). 1034 Draft Protocol Specification NFS version 4 October 1999 1036 fileid 20 uint64 READ 1037 A number uniquely 1038 identifying the file 1039 within the 1040 filesystem. 1042 files_avail 21 uint64 READ 1043 File slots available 1044 to this user on the 1045 filesystem containing 1046 this object - this 1047 should be the 1048 smallest relevant 1049 limit. 1051 files_free 22 uint64 READ 1052 Free file slots on 1053 the filesystem 1054 containing this 1055 object - this should 1056 be the smallest 1057 relevant limit. 1059 files_total 23 uint64 READ 1060 Total file slots on 1061 the filesystem 1062 containing this 1063 object. 1065 fs_locations 24 fs_locations READ 1066 Locations where this 1067 filesystem may be 1068 found. If the server 1069 returns NFS4ERR_MOVED 1070 as an error, this 1071 attribute must be 1072 supported. 1074 hidden 25 boolean R/W 1075 Is file considered 1076 hidden? 1078 homogeneous 26 boolean READ 1079 Whether or not this 1080 object's filesystem 1081 is homogeneous, i.e. 1082 whether pathconf is 1083 the same for all 1084 filesystem objects. 1086 maxfilesize 27 uint64 READ 1087 Maximum supported 1088 file size for the 1089 filesystem of this 1090 object. 1092 Draft Protocol Specification NFS version 4 October 1999 1094 maxlink 28 uint32 READ 1095 Maximum number of 1096 links for this 1097 object. 1099 maxname 29 uint32 READ 1100 Maximum filename size 1101 supported for this 1102 object. 1104 maxread 30 uint64 READ 1105 Maximum read size 1106 supported for this 1107 object. 1109 maxwrite 31 uint64 READ 1110 Maximum write size 1111 supported for this 1112 object. This 1113 attribute SHOULD be 1114 supported if the file 1115 is writable. Lack of 1116 this attribute can 1117 lead to the client 1118 either wasting 1119 bandwidth or not 1120 receiving the best 1121 performance. 1123 mime_type 32 utf8<> R/W 1124 MIME body 1125 type/subtype of this 1126 object. 1128 mode 33 uint32 R/W 1129 Unix-style permission 1130 bits for this object 1131 (deprecated in favor 1132 of ACLs) 1134 no_trunc 34 boolean READ 1135 If a name longer than 1136 name_max is used, 1137 will an error be 1138 returned or will the 1139 name be truncated? 1141 numlinks 35 uint32 READ 1142 Number of links to 1143 this object. 1145 owner 36 utf8<> R/W 1146 The string name of 1147 the owner of this 1148 object. 1150 Draft Protocol Specification NFS version 4 October 1999 1152 owner_group 37 utf8<> R/W 1153 The string name of 1154 the group of the 1155 owner of this object. 1157 quota_hard 38 uint64 READ 1158 Number of bytes of 1159 disk space beyond 1160 which the server will 1161 decline to allocate 1162 new space. 1164 quota_soft 39 uint64 READ 1165 Number of bytes of 1166 disk space at which 1167 the client may choose 1168 to warn the user 1169 about limited space. 1171 quota_used 40 uint64 READ 1172 Number of bytes of 1173 disk space occupied 1174 by the owner of this 1175 object on this 1176 filesystem. 1178 rawdev 41 specdata4 READ 1179 Raw device 1180 identifier. 1182 space_avail 42 uint64 READ 1183 Disk space in bytes 1184 available to this 1185 user on the 1186 filesystem containing 1187 this object - this 1188 should be the 1189 smallest relevant 1190 limit. 1192 space_free 43 uint64 READ 1193 Free disk space in 1194 bytes on the 1195 filesystem containing 1196 this object - this 1197 should be the 1198 smallest relevant 1199 limit. 1201 space_total 44 uint64 READ 1202 Total disk space in 1203 bytes on the 1204 filesystem containing 1205 this object. 1207 Draft Protocol Specification NFS version 4 October 1999 1209 space_used 45 uint64 READ 1210 Number of filesystem 1211 bytes allocated to 1212 this object. 1214 system 46 boolean R/W 1215 Whether or not this 1216 file is a system 1217 file. 1219 time_access 47 nfstime4 R/W 1220 The time of last 1221 access to the object. 1223 time_backup 48 nfstime4 R/W 1224 The time of last 1225 backup of the object. 1227 time_create 49 nfstime4 R/W 1228 The time of creation 1229 of the object. This 1230 attribute does not 1231 have any relation to 1232 the traditional Unix 1233 file attribute 1234 time'. 1236 time_delta 50 nfstime4 READ 1237 Smallest useful 1238 server time 1239 granularity. 1241 time_metadata 51 nfstime4 R/W 1242 The time of last 1243 meta-data 1244 modification of the 1245 object. 1247 time_modify 52 nfstime4 R/W 1248 The time since the 1249 epoch of last 1250 modification to the 1251 object. 1253 version 53 utf8<> R/W 1254 Version number of 1255 this document. 1257 volatility 54 nfstime4 READ 1258 Approximate time 1259 until next expected 1260 change on this 1261 filesystem, as a 1262 measure of 1263 volatility. 1265 Draft Protocol Specification NFS version 4 October 1999 1267 5.6. Interpreting owner and owner_group 1269 The recommended attributes "owner" and "owner_group" are represented 1270 in terms of a UTF-8 string. To avoid a representation that is tied 1271 to a particular underlying implementation at the client or server, 1272 the use of the UTF-8 string has been chosen. Note that section 6.1 1273 of [RFC2624] provides additional rationale. It is expected that the 1274 client and server will have their own local representation of owner 1275 and owner_group that is used for local storage or presentation to the 1276 end user. Therefore, it is expected that the when these attributes 1277 are transferred between the client and server that the local 1278 representation is translated to a syntax of the form 1279 "user@dns_domain". This will allow for a client and server that do 1280 not use the same local representation the ability to translate to a 1281 common syntax that can be interpreted by both. 1283 The translation is not specified as part of the protocol. This 1284 allows various solutions to be employed. For example, a local 1285 translation table may be consulted that maps between a numeric id to 1286 the user@dns_domain syntax. A name service may also be used to 1287 accomplish the translation. The 'dns_domain' portion of the owner 1288 string is meant to be a DNS domain name. For example, user@ietf.org. 1290 In the case where there is no translation available to the client or 1291 server, the attribute value must be constructed without the '@'. 1292 Therefore, the absence of the @ from the owner or owner_group 1293 attribute signifies that no translation was available and the 1294 receiver of the attribute should not place any special meaning with 1295 the attribute value. Even though the attribute value can not be 1296 translated, it may still be useful. In the case of a client, the 1297 attribute string may be used for local display of ownership. 1299 5.7. Access Control Lists 1301 The NFS ACL attribute is an array of access control entries (ACE). 1302 There are various access control entry types. The server is able to 1303 communicate which ACE types are support by returning the appropriate 1304 value within the aclsupport attribute. The types of ACEs are defined 1305 as follows: 1307 Type Description 1308 _____________________________________________________ 1309 ALLOW 1310 Explicitly grants the access defined in 1311 acemask4 to the file or directory. 1313 Draft Protocol Specification NFS version 4 October 1999 1315 DENY 1316 Explicitly denies the access defined in 1317 acemask4 to the file or directory. 1319 AUDIT 1320 LOG (system dependant) any access 1321 attempt to a file or directory which 1322 uses an access method which is a subset 1323 of acemask4. 1325 ALARM 1326 Generate a system ALARM (system 1327 dependant) when any access attempt is 1328 made to a file or directory which is a 1329 subset of acemask4 1331 The NFS ACE attribute is defined as follows: 1333 struct nfsace4 { 1334 acetype4 type; 1335 aceflag4 flag; 1336 acemask4 access_mask; 1337 utf8string who; 1338 }; 1340 Each nfsace4 entry is assumed to be processed in order by the server. 1341 The first Access Control Entry is used where both the "who" and the 1342 "access_mask" match the requester and the type of access desired. Any 1343 later additional Access Control Entries which also match are ignored. 1345 5.7.1. ACE type 1347 The semantics of the 'type' field follow the descriptions provided 1348 above. 1350 5.7.2. ACE flag 1352 The 'flag' field contains values based on the following descriptions. 1354 ACE4_FILE_INHERIT_ACE 1356 Can be placed on a directory and indicates that this ACE should be 1357 added to each new non-directory file created. 1359 ACE4_DIRECTORY_INHERIT_ACE 1361 Draft Protocol Specification NFS version 4 October 1999 1363 Can be placed on a directory and indicates that this ACE should be 1364 added to each new directory created. 1366 ACE4_INHERIT_ONLY_ACE 1368 Can be placed on a directory but does not apply to the directory, 1369 only to newly created files/directories as specified by the above two 1370 flags. 1372 ACE4_NO_PROPAGATE_INHERIT_ACE 1374 Can be placed on a directory. Normally when a new directory is 1375 created and an ACE exists on the parent directory which is marked 1376 ACL4_DIRECTORY_INHERIT_ACE, two ACEs are placed on the new directory. 1377 One for the directory itself and one which is an inheritable ACE for 1378 newly created directories. This flag tells the O/S to not place an 1379 ACE on the newly created directory which is inheritable by 1380 subdirectories of the created directory. 1382 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 1384 ACL4_FAILED_ACCESS_ACE_FLAG 1386 Both indicate for AUDIT and ALARM which state to log the event. On 1387 every ACCESS or OPEN call which occurs on a file or directory which 1388 has an ACL that is of type ACE4_SYSTEM_AUDIT_ACE_TYPE or 1389 ACE4_SYSTEM_ALARM_ACE_TYPE, the attempted access is compared to the 1390 ace4mask of these ACLs. If the access is a subset of ace4mask and the 1391 identifier match, an AUDIT trail or an ALARM is generated. By 1392 default this happens regardless of the success or failure of the 1393 ACCESS or OPEN call. 1395 The flag ACE4_SUCCESSFUL_ACCESS_ACE_FLAG only produces the AUDIT or 1396 ALARM if the ACCESS or OPEN call is successful. The 1397 ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS 1398 or OPEN call fails. 1400 ACE4_IDENTIFIER_GROUP 1402 Indicates that the "who" refers to a GROUP as defined under Unix. 1404 Draft Protocol Specification NFS version 4 October 1999 1406 5.7.3. ACE Access Mask 1408 The access_mask field contains values based on the following: 1410 Access Description 1411 ____________________________________________________________________ 1412 READ_DATA 1413 Permission to read the data of the file 1414 LIST_DIRECTORY 1415 Permission to list the contents of a 1416 directory 1417 WRITE_DATA 1418 Permission to modify the file's data 1419 ADD_FILE 1420 Permission to add a new file to a 1421 directory 1422 APPEND_DATA 1423 Permission to append data to a file 1424 ADD_SUBDIRECTORY 1425 Permission to create a subdirectory to a 1426 directory 1427 READ_STREAMS 1428 Permission to read the additional 1429 streams of a file 1430 WRITE_STREAMS 1431 Permission to write the additional 1432 streams of a file 1433 EXECUTE 1434 Permission to execute a file 1435 DELETE_CHILD 1436 Permission to delete a file or directory 1437 within a directory 1438 READ_ATTRIBUTES 1439 The ability to read basic attributes 1440 (non-acls) of a file 1441 WRITE_ATTRIBUTES 1442 Permission to change basic attributes 1443 (non-acls) of a file 1445 READ_CONTROL 1446 ? 1447 READ_EXTENDED_ATTRIBUTES 1448 ? 1449 WRITE_EXTENDED_ATTRIBUTES 1450 ? 1452 DELETE 1453 Permission to Delete the File, IF FILE 1454 BASED 1455 READ_ACL 1456 Permission to Read the ACL 1457 WRITE_ACL 1458 Permission to Write the ACL 1459 WRITE_OWNER 1460 Permission to change the owner 1461 SYNCHRONIZE 1462 Allow the forcing of mutual-exclusion to 1463 the file 1465 5.7.4. ACE who 1467 There are several special identifiers ("who") which need to be 1468 understood universally. Some of these identifiers cannot be 1469 understood when an NFS client accesses the server, but have meaning 1470 when a local process accesses the file. The ability to display and 1472 Draft Protocol Specification NFS version 4 October 1999 1474 modify these permissions is permitted over NFS. 1476 Who Description 1477 _______________________________________________________________ 1478 "OWNER" 1479 The owner of the file. 1480 "GROUP" 1481 The group associated with the file. 1482 "EVERYONE" 1483 The world. 1484 "INTERACTIVE" 1485 Accessed from an interactive terminal. 1486 "NETWORK"- 1487 cessed via the network. 1488 "DIALUP" 1489 Accessed as a dialup user to the server. 1490 "BATCH" 1491 Accessed from a batch job. 1492 "ANONYMOUS" 1493 Accessed without any authentication. 1494 "AUTHENTICATED" 1495 Any authenticated user (opposite of 1496 ANONYMOUS) 1497 "SERVICE" 1498 Access from a system service. 1500 To avoid conflict these special identifiers should be of the form 1501 "xxxx@". For example: ANONYMOUS@. 1503 Draft Protocol Specification NFS version 4 October 1999 1505 6. Filesystem Migration and Replication 1507 With the use of the recommended attribute "fs_locations", the NFS 1508 version 4 server has a method of providing filesystem migration or 1509 replication services. For the purposes of migration and replication, 1510 a filesystem will be defined as all files that share a given fsid 1511 (major and minor values are the same). 1513 The fs_locations attribute provides a list of filesystem locations. 1514 These locations are specified by providing the server name (either 1515 DNS domain or IP address) and the path name representing the root of 1516 the filesystem. Depending on the type of service being provided, the 1517 list will provide a new or alternate locations for the filesystem. 1518 The client will use this information to redirect its requests to the 1519 new server. 1521 6.1. Replication 1523 It is expected that filesystem replication will be used in the case 1524 of read-only data. Typically, the filesystem will be replicated 1525 amongst two or more servers. The fs_locations attribute will provide 1526 the list of these locations to the client. On first access of the 1527 filesystem, the client should obtain the value of the fs_locations 1528 attribute. If, in the future, the client finds the server 1529 unresponsive, the client may attempt to use another server specified 1530 by fs_locations. 1532 If applicable, the client must take the appropriate steps to recover 1533 valid filehandles from the new server. This is described in more 1534 detail in the following sections. 1536 6.2. Migration 1538 Filesystem migration is used to move a filesystem from one server to 1539 another. Migration is typically used for a filesystem that is 1540 writable and has a single copy. The expected use of migration is for 1541 load balancing or general resource reallocation. The protocol does 1542 not specify how the filesystem will be moved between servers. This 1543 server-to-server transfer mechanism is left to the server 1544 implementor. However, the method used to communicate the migration 1545 event between client and server is specified here. 1547 Once the servers participating in the migration have completed the 1548 move of the filesystem, the error NFS4ERR_MOVED will be returned for 1549 subsequent requests received by the original server. The 1550 NFS4ERR_MOVED error is returned for all operations except GETATTR. 1552 Draft Protocol Specification NFS version 4 October 1999 1554 Upon receiving the NFS4ERR_MOVED error, the client will obtain the 1555 value of the fs_locations attribute. The client will then use the 1556 contents of the attribute to redirect its requests to the specified 1557 server. To facilitate the use of GETATTR operations such as PUTFH 1558 must also be accepted by the server for the migrated filesystem's 1559 filehandles. Note that if the server returns NFS4ERR_MOVED, the 1560 server MUST support the fs_locations attribute. 1562 If the client requests more attributes than fs_locations, the server 1563 may return fs_locations only. This is to be expected since the 1564 server has migrated the filesystem and may not have a method of 1565 obtaining additional attribute data. 1567 The server implementor needs to be careful in developing a migration 1568 solution. The server must consider all of the state information 1569 clients may have outstanding at the server. This includes but is not 1570 limited to locking/share state, delegation state, and asynchronous 1571 file writes which are represented by WRITE and COMMIT verifiers. The 1572 server should strive to minimize the impact on its clients during and 1573 after the migration process. 1575 6.3. Interpretation of the fs_locations Attribute 1577 The fs_location attribute is structured in the following way: 1579 struct fs_location { 1580 utf8string server<>; 1581 pathname4 rootpath; 1582 }; 1584 struct fs_locations { 1585 pathname4 fs_root; 1586 fs_location locations<>; 1587 }; 1589 The fs_location struct is used to represent the location of a 1590 filesystem by providing a server name and the path to the root of the 1591 filesystem. For a multi-homed server or a set of servers that use 1592 the same rootpath, an array of server names may be provided. An 1593 entry in the server array is an UTF8 string and represents one of a 1594 traditional DNS host name, IPv4 address, or IPv6 address. It is not 1595 a requirement that all servers that share the same rootpath be listed 1596 in one fs_location struct. The array of server names is provided for 1597 convenience. Servers that share the same rootpath may also be listed 1598 in separate fs_location entries in the fs_locations attribute. 1600 The fs_locations struct and attribute then contains an array of 1602 Draft Protocol Specification NFS version 4 October 1999 1604 locations. Since the namespace of each server may be constructed 1605 differently, the "fs_root" field is provided. The path represented 1606 by fs_root represents the location of the filesystem in the server's 1607 namespace. Therefore, the fs_root path is only associated with the 1608 server from which the fs_locations attribute was obtained. The 1609 fs_root path is meant to aid the client in locating the filesystem at 1610 the various servers listed. 1612 As an example, there is a replicated file system located at two 1613 servers (servA and servB). At servA the filesystem is located at 1614 path "/a/b/c". At servB the filesystem is located at path "/x/y/z". 1615 In this example the client accesses the filesystem first at servA 1616 with a multi-component lookup path of "/a/b/c/d". Since the client 1617 used a multi-component lookup to obtain the filehandle at "/a/b/c/d", 1618 it is unaware that the filesystem's root is located in servA's 1619 namespace at "/a/b/c". When the client switches to servB, it will 1620 need to determine that the directory it first referenced at servA is 1621 now represented by the path "/x/y/z/d" on servB. To facilitate this, 1622 the fs_locations attribute provided by servA would have a fs_root 1623 value of "/a/b/c" and two entries in fs_location. One entry in 1624 fs_location will be for itself (servA) and the other will be for 1625 servB with a path of "/x/y/z". With this information, the client is 1626 able to substitute "/x/y/z" for the "/a/b/c" at the beginning of its 1627 access path and construct "/x/y/z/d" to use for the new server. 1629 6.4. Filehandle Recovery for Migration or Replication 1631 Filehandles for filesystems that are replicated or migrated have the 1632 same semantics as for filesystems that are not replicated or 1633 migrated. For example, if a filesystem has persistent filehandles 1634 and it is migrated to another server, the filehandle values for the 1635 filesystem will be valid at the new server. 1637 The same is true for a filesystem which is made up of volatile 1638 filehandles. In fact, in this case the client should expect that the 1639 new server will return NFS4ERR_EXPIRED when old filehandles are 1640 presented; the client will need to recover the filehandles 1641 appropriately. 1643 Draft Protocol Specification NFS version 4 October 1999 1645 7. NFS Server Namespace 1647 7.1. Server Exports 1649 On a UNIX server the name-space describes all the files reachable by 1650 pathnames under the root directory "/". On a Windows NT server the 1651 name-space constitutes all the files on disks named by mapped disk 1652 letters. NFS server administrators rarely make the entire server's 1653 file-system name-space available to NFS clients. Typically, pieces 1654 of the name-space are made available via an "export" feature. In 1655 previous versions of NFS, the root file-handle for each export is 1656 obtained through the MOUNT protocol; the client sends a string that 1657 identifies the export of name-space and the server returns the root 1658 file-handle for it. The MOUNT protocol supports an EXPORTS procedure 1659 that will enumerate the server's exports. 1661 7.2. Browsing Exports 1663 The NFS version 4 protocol provides a root file-handle that clients 1664 can use to obtain file-handles for these exports via a multi- 1665 component LOOKUP. A common user experience is to use a graphical 1666 user interface (perhaps a file "Open" dialog window) to find a file 1667 via progressive browsing through a directory tree. The client must be 1668 able to move from one export to another export via single-component, 1669 progressive LOOKUP operations. 1671 This style of browsing is not well supported by NFS version 2 and 3 1672 protocols. The client expects all LOOKUP operations to remain within 1673 a single server file-system, i.e. the device attribute will not 1674 change. This prevents a client from taking name-space paths that 1675 span exports. 1677 An automounter on the client can obtain a snapshot of the server's 1678 name-space using the EXPORTS procedure of the MOUNT protocol. If it 1679 understands the server's pathname syntax, it can create an image of 1680 the server's name-space on the client. The parts of the name-space 1681 that are not exported by the server are filled in with a "pseudo 1682 file-system" that allows the user to browse from one mounted file- 1683 system to another. There is a drawback to this representation of the 1684 server's name-space on the client: it is static. If the server 1685 administrator adds a new export the client will be unaware of it. 1687 Draft Protocol Specification NFS version 4 October 1999 1689 7.3. Server Pseudo File-System 1691 NFS version 4 servers avoid this name-space inconsistency by 1692 presenting all the exports within the framework of a single server 1693 name-space. An NFS version 4 client uses LOOKUP and READDIR 1694 operations to browse seamlessly from one export to another. Portions 1695 of the server name-space that are not exported are bridged via a 1696 "pseudo file-system" that provides a view of exported directories 1697 only. A pseudo file-system has a unique fsid and behaves like a 1698 normal, read-only file-system. 1700 Based on the construction of the server's name space, it is 1701 possible that multiple pseudo filesystems may exist. For 1702 example, 1704 /a pseudo filesystem 1705 /a/b real filesystem 1706 /a/b/c pseudo filesystem 1707 /a/b/c/d real filesystem 1709 Need to discuss the ramifications of multiple pseudo 1710 filesystems. 1712 7.4. Multiple Roots 1714 DOS, Windows 95, 98 and NT are sometimes described as having 1715 "multiple roots". File-Systems are commonly represented as disk 1716 letters. MacOS represents file-systems as top-level names. NFS 1717 version 4 servers for these platforms can construct a pseudo file- 1718 system above these root names so that disk letters or volume names 1719 are simply directory names in the pseudo-root. 1721 7.5. Filehandle Volatility 1723 The nature of the server's pseudo file-system is that it is a logical 1724 representation of file-system(s) available from the server. 1725 Therefore, the pseudo file-system is most likely constructed 1726 dynamically when the NFS version 4 is first instantiated. It is 1727 expected the pseudo file-system may not have an on-disk counterpart 1728 from which persistent filehandles could be constructed. Even though 1729 it is preferable that the server provide persistent filehandles for 1730 the pseudo file-system, the NFS client should expect that pseudo 1731 file-system file-handles are volatile. This can be confirmed by 1732 checking the associated "persistent_fh" attribute for those 1734 Draft Protocol Specification NFS version 4 October 1999 1736 filehandles in question. If the filehandles are volatile, the NFS 1737 client must be prepared to recover a filehandle value (i.e. with a v4 1738 multi-component LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 1740 7.6. Exported Root 1742 If the server's root file-system is exported, it might be easy to 1743 conclude that a pseudo-file-system is not needed. This would be 1744 wrong. Assume the following file-systems on a server: 1746 / disk1 (exported) 1747 /a disk2 (not exported) 1748 /a/b disk3 (exported) 1750 Because disk2 is not exported, disk3 cannot be reached with simple 1751 LOOKUPs. The server must bridge the gap with a pseudo-file-system. 1753 7.7. Mount Point Crossing 1755 The server file-system environment may be constructed in such a way 1756 that one file-system contains a directory which is 'covered' or 1757 mounted upon by a second file-system. For example: 1759 /a/b (file system 1) 1760 /a/b/c/d (file system 2) 1762 The pseudo file-system for this server may be constructed to look 1763 like: 1765 / (place holder/not exported) 1766 /a/b (file system 1) 1767 /a/b/c/d (file system 2) 1769 It is the server's responsibility to present the pseudo file-system 1770 that is complete to the client. If the client sends a lookup request 1771 for the path "/a/b/c/d", the server's response is the filehandle of 1772 the file system "/a/b/c/d". In previous versions of NFS, the server 1773 would respond with the directory "/a/b/d/d" within the file-system 1774 "/a/b". 1776 The NFS client will be able to determine if it crosses a server mount 1777 point by a change in the value of the "fsid" attribute. 1779 Draft Protocol Specification NFS version 4 October 1999 1781 7.8. Security Policy and Namespace Presentation 1783 The application of the server's security policy needs to be carefully 1784 considered by the implementor. One may choose to limit the 1785 viewability of portions of the pseudo file-system based on the 1786 server's perception of the client's ability to authenticate itself 1787 properly. However with the support of multiple security mechanisms 1788 and the ability to negotiate the appropriate use of these mechanisms, 1789 the server is unable to properly determine if a client will be able 1790 to authenticate itself. If, based on its policies, the server 1791 chooses to limit the contents of the pseudo file-system, the server 1792 may effectively hide file-systems from a client that may otherwise 1793 have legitimate access. 1795 7.9. Summary 1797 NFS version 4 provides LOOKUP and READDIR operations for browsing of 1798 NFS file-systems. These operations are also used to browse server 1799 exports. A v4 server supports export browsing by including exported 1800 directories in a pseudo-file-system. A browsing client can cross 1801 seamlessly between a pseudo-file-system and a real, exported file- 1802 system. Clients must support volatile filehandles and recognize 1803 mount point crossing of server file-systems. 1805 Draft Protocol Specification NFS version 4 October 1999 1807 8. File Locking 1809 Integrating locking into NFS necessarily causes it to be state-full, 1810 with the invasive nature of "share" file locks it becomes 1811 substantially more dependent on state than the traditional 1812 combination of NFS and NLM [XNFS]. There are three components to 1813 making this state manageable: 1815 o Clear division between client and server 1817 o Ability to reliably detect inconsistency in state between client 1818 and server 1820 o Simple and robust recovery mechanisms 1822 In this model, the server owns the state information. The client 1823 communicates its view of this state to the server as needed. The 1824 client is also able to detect inconsistent state before modifying a 1825 file. 1827 To support Windows "share" locks, it is necessary to atomically open 1828 or create files. Having a separate share/unshare operation will not 1829 allow correct implementation of the Windows OpenFile API. In order 1830 to correctly implement share semantics, the existing mechanisms used 1831 when a file is opened or created (LOOKUP, CREATE, ACCESS) need to be 1832 replaced. NFS V4 will have an OPEN procedure that subsumes the 1833 functionality of LOOKUP, CREATE, and ACCESS. However, because many 1834 operations require a file handle, the traditional LOOKUP is preserved 1835 to map a file name to file handle without establishing state on the 1836 server. Policy of granting access or modifying files is managed by 1837 the server based on the client's state. It is believed that these 1838 mechanisms can implement policy ranging from advisory only locking to 1839 full mandatory locking. While ACCESS is just a subset of OPEN, the 1840 ACCESS procedure is maintained as a lighter weight mechanism. 1842 8.1. Definitions 1844 Lock The term "lock" will be used to refer to both record 1845 (byte-range) locks as well as file (share) locks unless 1846 specifically stated otherwise. 1848 Client Throughout this proposal the term "client" is used to 1849 indicate the entity that maintains a set of locks on behalf 1850 of one or more applications. The client is responsible for 1851 crash recovery of those locks it manages. Multiple clients 1852 may share the same transport and multiple clients may exist 1854 Draft Protocol Specification NFS version 4 October 1999 1856 on the same network node. 1858 Clientid A 64-bit quantity returned by a server that uniquely 1859 corresponds to a client supplied Verifier and ID. 1861 Lease An interval of time defined by the server for which the 1862 client is irrevokeably granted a lock. At the end of a 1863 lease period the lock may be revoked if the lease has not 1864 been extended. The lock must be revoked if a conflicting 1865 lock has been granted after the lease interval. All leases 1866 granted by a server have the same fixed interval. 1868 Stateid A 64-bit quantity returned by a server that uniquely 1869 defines the locking state granted by the server for a 1870 specific lock owner for a specific file. A stateid 1871 composed of all bits 0 or all bits 1 have special meaning 1872 and are reserved. 1874 Verifier A 32-bit quantity generated by the client that the server 1875 can use to determine if the client has restarted and lost 1876 all previous lock state. 1878 8.2. Locking 1880 It is assumed that manipulating a lock is rare when compared to I/O 1881 operations. It is also assumed that crashes and network partitions 1882 are relatively rare. Therefore it is important that I/O operations 1883 have a light weight mechanism to indicate if they possess a held 1884 lock. A lock request contains the heavy weight information required 1885 to establish a lock and uniquely define the lock owner. 1887 The following sections describe the transition from the heavy weight 1888 information to the eventual stateid used for most client and server 1889 locking and lease interactions. 1891 8.2.1. Client ID 1893 For each LOCK request, the client must identify itself to the server. 1894 This is done in such a way as to allow for correct lock 1895 identification and crash recovery. Client identification is 1896 accomplished with two values. 1898 o A verifier that is used to detect client reboots. 1900 o A variable length opaque array to uniquely define a client. 1902 For an operating system this may be a fully qualified host 1904 Draft Protocol Specification NFS version 4 October 1999 1906 name or IP address, and for a user level NFS client it may 1907 additionally contain a process id or other unique sequence. 1909 The data structure for the Client ID would then appear as: 1910 struct nfs_client_id { 1911 opaque verifier[4]; 1912 opaque id<>; 1913 } 1915 It is possible through the mis-configuration of a client or the 1916 existence of a rogue client that two clients end up using the same 1917 nfs_client_id. This situation is avoided by 'negotiating' the 1918 nfs_client_id between client and server with the use of the 1919 SETCLIENTID. The following describes the two scenarios of 1920 negotiation. 1922 1 Client has never connected to the server 1924 In this case the client generates an nfs_client_id and 1925 unless another client has the same nfs_client_id.id field, 1926 the server accepts the request. The server also records the 1927 principal (or principal to uid mapping) from the credential 1928 in the RPC request that contains the nfs_client_id 1929 negotiation request. 1931 Two clients might still use the same nfs_client_id.id due 1932 to perhaps configuration error (say a High Availability 1933 configuration where the nfs_client_id.id is derived from 1934 the ethernet controller address and both systems have the 1935 same address). In this case, the result is a switched 1936 union that returns in addition to NFS4ERR_CLID_INUSE, the 1937 network address (the rpcbind netid and universal address) 1938 of the client that is using the id. 1940 2 Client is re-connecting to the server after a client reboot 1942 In this case, the client still generates an nfs_client_id 1943 but the nfs_client_id.id field will be the same as the 1944 nfs_client_id.id generated prior to reboot. If the server 1945 finds that the principal/uid is equal to the previously 1946 "registered" nfs_client_id.id, then locks associated with 1947 the old nfs_client_id are immediately released. If the 1948 principal/uid is not equal, then this is a rogue client and 1949 the request is returned in error. For more discussion of 1950 crash recovery semantics, see the section on "Crash 1951 Recovery" 1953 Draft Protocol Specification NFS version 4 October 1999 1955 In both cases, upon success, NFS4_OK is returned. To help reduce the 1956 amount of data transferred on OPEN and LOCK, the server will also 1957 return a unique 64-bit clientid value that is a short hand reference 1958 to the nfs_client_id values presented by the client. From this point 1959 forward, the client can use the clientid to refer to itself. 1961 8.2.2. nfs_lockowner and stateid Definition 1963 When requesting a lock, the client must present to the server the 1964 clientid and an identifier for the owner of the requested lock. 1965 These two fields are referred to as the nfs_lockowner and the 1966 definition of those fields are: 1968 o A clientid returned by the server as part of the clients use of 1969 the SETCLIENTID procedure 1971 o A variable length opaque array used to uniquely define the owner 1972 of a lock managed by the client. 1974 This may be a thread id, process id, or other unique value. 1976 When the server grants the lock it responds with a unique 64-bit 1977 stateid. The stateid is used as a short hand reference to the 1978 nfs_lockowner, since the server will be maintaining the 1979 correspondence between them. 1981 8.2.3. Use of the stateid 1983 All I/O requests contain a stateid. If the nfs_lockowner performs 1984 I/O on a range of bytes within a locked range, the stateid returned 1985 by the server must be used to indicate the appropriate lock (record 1986 or share) is held. If no state is established by the client, either 1987 record lock or share lock, a stateid of all bits 0 is used. If no 1988 conflicting locks are held on the file, the server may grant the I/O 1989 request. If a conflict with an explicit lock occurs, the request is 1990 failed (NFS4ERR_LOCKED). This allows "mandatory locking" to be 1991 implemented. 1993 A stateid of all bits 1 allows read requests to bypass locking checks 1994 at the server. However, write requests with stateid with bits all 1 1995 does not bypass file locking requirements. 1997 An explicit lock may not be granted while an I/O operation with 1998 conflicting implicit locking is being performed. 2000 Draft Protocol Specification NFS version 4 October 1999 2002 The byte range of a lock is indivisible. A range may be locked, 2003 unlocked, or changed between read and write but may not have 2004 subranges unlocked or changed between read and write. This is the 2005 semantics provided by Win32 but only a subset of the semantics 2006 provided by Unix. It is expected that Unix clients can more easily 2007 simulate modifying subranges than Win32 servers adding this feature. 2009 8.2.4. Sequencing of Lock Requests 2011 Locking is different than most NFS operations as it requires "at- 2012 most-one" semantics that are not provided by ONC RPC. In the face of 2013 retransmission or reordering, lock or unlock requests must have a 2014 well defined and consistent behavior. To accomplish this each lock 2015 request contains a sequence number that is a monotonically increasing 2016 integer. Different nfs_lockowners have different sequences. The 2017 server maintains the last sequence number (L) received and the 2018 response that was returned. If a request with a previous sequence 2019 number (r < L) is received it is silently ignored as its response 2020 must have been received before the last request (L) was sent. If a 2021 duplicate of last request (r == L) is received, the stored response 2022 is returned. If a request beyond the next sequence (r == L + 2) is 2023 received it is silently ignored. Sequences are reinitialized 2024 whenever the client verifier changes. 2026 8.3. Blocking Locks 2028 Some clients require the support of blocking locks. The current 2029 proposal lacks a call-back mechanism, similar to NLM, to notify a 2030 client when the lock has been granted. Clients have no choice but to 2031 continually poll for the lock, which presents a fairness problem. 2032 Two new lock types are added, READW and WRITEW used to indicate to 2033 the server that the client is requesting a blocking lock. The server 2034 should maintain an ordered list of pending blocking locks. When the 2035 conflicting lock is released, the server may wait the lease period 2036 for the first client to re-request the lock. After the lease period 2037 expires the next waiting client request is allowed the lock. Clients 2038 are required to poll at an interval sufficiently small that it is 2039 likely to acquire the lock in a timely manner. The server is not 2040 required to maintain a list of pending blocked locks as it is used to 2041 increase fairness and not correct operation. Because of the 2042 unordered nature of crash recovery, storing of lock state to stable 2043 storage would be required to guarantee ordered granting of blocking 2044 locks. 2046 Draft Protocol Specification NFS version 4 October 1999 2048 8.4. Lease Renewal 2050 The purpose of a lease is to allow a server to remove stale locks 2051 that are held by a client that has crashed or is otherwise 2052 unreachable. It is not a mechanism for cache consistency and lease 2053 renewals may not be denied if the lease interval has not expired. 2054 Any I/O request that has been made with a valid stateid is a positive 2055 indication that the client is still alive and locks are being 2056 maintained. This becomes an implicit renewal of the lease. In the 2057 case no I/O has been performed within the lease interval, a lease can 2058 be renewed by having the client issue a zero length READ. Because 2059 the nfs_lockowner contains a unique client value, any stateid for a 2060 client will renew all leases for locks held with the same client 2061 field. This will allow very low overhead lease renewal that scales 2062 extremely well. In the typical case, no extra RPC calls are needed 2063 and in the worst case one RPC is required every lease period 2064 regardless of the number of locks held by the client. 2066 8.5. Crash Recovery 2068 The important requirement in crash recovery is that both the client 2069 and the server know when the other has failed. Additionally it is 2070 required that a client sees a consistent view of data across server 2071 reboots. All I/O operations that may have been queued within the 2072 client or network buffers must wait until the client has successfully 2073 recovered the locks protecting the I/O operations. 2075 8.5.1. Client Failure and Recovery 2077 In the event that a client fails, the server may recover the client's 2078 locks when the associated leases have expired. Conflicting locks 2079 from another client may only be granted after this lease expiration. 2080 If the client is able to restart or reinitialize within the lease 2081 period the client may be forced to wait the remainder of the lease 2082 period before obtaining new locks. 2084 To minimize client delay upon restart, lock requests contain a 2085 verifier field in the lock_owner. This verifier is part of the 2086 initial SETCLIENTID call made by the client. Since the verifier will 2087 be changed by the client upon each initialization, the server can 2088 compare a new verifier to the the verifier associated with currently 2089 held locks and determine that they do not match. This signifies the 2090 client's new instantiation and loss of locking state. As a result, 2091 the server is free to release all locks held which are associated 2092 with the old verifier. 2094 Draft Protocol Specification NFS version 4 October 1999 2096 For secure environments, a change in the verifier must only cause the 2097 release of locks associated with the authenticated requester. This 2098 is required to prevent a rogue entity from freeing otherwise valid 2099 locks. Note that the verifier must have the same uniqueness 2100 properties of the COMMIT verifier. 2102 8.5.2. Server Failure and Recovery 2104 If the server fails and loses locking state, the server must wait the 2105 lease period before granting any new locks or allowing any I/O. An 2106 I/O request during the grace period with a stale stateid will fail 2107 with NFS4ERR_GRACE. To recover the lock and associate state, the 2108 client will reissue the lock request with reclaim set to TRUE. Upon 2109 receiving a successful reply and associated stateid, the client may 2110 reissue the I/O request with the new stateid. 2112 Any time a client receives an NFS4ERR_GRACE error, the client must 2113 assume that all locking state associated with the server returning 2114 the error has been lost. The client should start recovering all 2115 outstanding locks upon receiving NFS4ERR_GRACE. 2117 If the server receives a lock request during its grace period that 2118 does not have reclaim set to TRUE, the server must return 2119 NFS4ERR_GRACE. This error return will trigger the client to recover 2120 all of its locking state by reclaiming locks. 2122 A lock request outside the server's grace period with reclaim set to 2123 TRUE can only succeed if the server can guarantee that no conflicting 2124 lock or I/O request has been granted since reboot. 2126 8.5.3. Network Partitions and Recovery 2128 If the duration of a network partition is greater than the lease 2129 period provided by the server, the server will have not received a 2130 lease renewal from the client. If this occurs, the server may free 2131 all locks held for the client. As a result, all stateids held by the 2132 client will become invalid. Once the client is able to reach the 2133 server after such a network partition, all I/O submitted by the 2134 client with the now invalid stateids will fail with the server 2135 returning the error NFS4ERR_EXPIRED. Once this error is received, 2136 the client will suitably notify the application that held the lock. 2138 As a courtesy to the client or optimization, the server may continue 2139 to hold locks on behalf of a client for which recent communication 2140 has extended beyond the lease period. If the server receives a lock 2141 or I/O request that conflicts with one of these courtesy locks, the 2143 Draft Protocol Specification NFS version 4 October 1999 2145 server must free the courtesy lock and grant the new request. 2147 In the event of a network partition with a duration extending beyond 2148 the expiration of a client's leases, the server MUST employ a method 2149 of recording this fact in its stable storage. Conflicting locks 2150 requests from another client may be serviced after the lease 2151 expiration. There are various scenarios involving server failure 2152 after such an event that require the storage of these lease 2153 expirations or network partitions. One scenario is as follows: 2155 A client holds a lock at the server and encounters a 2156 network partition and is unable to renew the associated 2157 lease. A second client obtains a conflicting lock and then 2158 frees the lock. After the unlock request by the second 2159 client, the server reboots or reinitializes. Once the 2160 server recovers, the network partition heals and the 2161 original client attempts to reclaim the original lock. 2163 In this scenario and without any state information, the server will 2164 allow the reclaim and the client will be in an inconsistent state 2165 because the server or the client has no knowledge of the conflicting 2166 lock. 2168 The server may choose to store this lease expiration or network 2169 partitioning state in a way that will only identify the client as a 2170 whole. Note that this may potentially lead to lock reclaims being 2171 denied unnecessarily because of a mix of conflicting and non- 2172 conflicting locks. The server may also choose to store information 2173 about each lock that has an expired lease with an associated 2174 conflicting lock. The choice of the amount and type of state 2175 information that is stored is left to the implementor. In any case, 2176 the server must have enough state information to enable correct 2177 recovery from multiple partitions and multiple server failures. 2179 8.6. Server Revocation of Locks 2181 At any point, the server can revoke locks held by a client and the 2182 client must be prepared for this event. When the client detects that 2183 its locks have been or may have been revoked, the client is 2184 responsible for validating the state information between itself and 2185 the server. Validating locking state for the client means that it 2186 must verify or reclaim state for each lock currently held. 2188 The first instance of lock revocation is upon server reboot or re- 2189 initialization. In this instance the client will receive an error or 2190 NFS4ERR_GRACE and the client will proceed with normal crash recovery 2191 as described in the previous section. 2193 Draft Protocol Specification NFS version 4 October 1999 2195 The second lock revocation event can occur as a result of 2196 administrative intervention within the lease period. While this is 2197 considered a rare event, it is possible that the server's 2198 administrator has decided to release or revoke a particular lock held 2199 by the client. As a result of revocation, the client will receive an 2200 error of NFS4ERR_EXPIRED and the error is received within the lease 2201 period for the lock. In this instance the client may assume that 2202 only the lock_owner's locks have been lost. The client notifies the 2203 lock holder appropriately. The client may not assume the lease 2204 period has been renewed as a result of failed operation. 2206 The third lock revocation event is the inability to renew the lease 2207 period. While this is considered a rare or unusual event, the client 2208 must be prepared to recover. Both the server and client will be able 2209 to detect the failure to renew the lease and are capable of 2210 recovering without data corruption. For the server, it tracks the 2211 last renewal event serviced for the client and knows when the lease 2212 will expire. Similarly, the client must track operations which will 2213 renew the lease period and is able to determine lease period 2214 expiration. 2216 When the client determines that the lease period has expired, the 2217 client must mark all locks held for the associated lease as 2218 "unvalidated". This means the client has been unable to re-establish 2219 or confirm the appropriate lock state with the server. As described 2220 in the previous section on crash recovery, there are scenarios in 2221 which the server may grant conflicting locks after the lease period 2222 has expired for a client. Once the lease period has expired, the 2223 client must validate each lock it has held to ensure that a 2224 conflicting lock has not been granted. The client may accomplish 2225 this task by issuing an I/O request, either a pending I/O or zero 2226 length read. If the response to the request is success, the client 2227 has validated the lock and re-established the appropriate state 2228 between itself and the server. If the I/O request is not successful, 2229 the lock was revoked by the server and the client must notify the 2230 owner. 2232 8.7. Share Reservations 2234 A share reservation is a mechanism to control access to a file. It 2235 is a separate and independent mechanism from record locking. When a 2236 client opens a file, it issues an OPEN request to the server 2237 specifying the type of access required (READ, WRITE, or BOTH) and the 2238 type of access to deny others (deny NONE, READ, WRITE, or BOTH). If 2239 the OPEN fails the client will fail the applications open request. 2241 Pseudo-code definition of the semantics: 2243 Draft Protocol Specification NFS version 4 October 1999 2245 if ((request.access & file_state.deny)) || 2246 (request.deny & file_state.access)) 2247 return (NFS4ERR_DENIED) 2249 8.8. OPEN/CLOSE Procedures 2251 To provide correct share semantics, a client MUST use the OPEN 2252 procedure to obtain the initial file handle and indicate the desired 2253 access and what if any access to deny. Even if the client intends to 2254 use a stateid of all 0's or all 1's, it must still obtain the 2255 filehandle for the regular file with the OPEN procedure. For clients 2256 that do not have a deny mode built into their open API, deny equal to 2257 NONE should be used. 2259 The OPEN procedure with the CREATE flag, also subsumes the CREATE 2260 procedure for regular files as used in previous versions of NFS, 2261 allowing a create with a share to be done atomicly. 2263 Will expand on create semantics here. 2265 The CLOSE procedure removes all share locks held by the lock_owner on 2266 that file. If record locks are held they should be explicitly 2267 unlocked. Some servers may not support the CLOSE of a file that 2268 still has record locks held; if so, CLOSE will fail and return an 2269 error. 2271 The LOOKUP procedure is preserved and will return a file handle 2272 without establishing any lock state on the server. Without a valid 2273 stateid, the server will assume the client has the least access. For 2274 example, a file opened with deny READ/WRITE cannot be accessed using 2275 a file handle obtained through LOOKUP. 2277 Draft Protocol Specification NFS version 4 October 1999 2279 9. Client-Side Caching 2281 Client-side caching of data, of file attributes, and of file names is 2282 essential to providing good performance in NFS. Providing dis- 2283 tributed cache-coherence is a difficult problem and previous versions 2284 of NFS have not attempted it. Instead, several client implementation 2285 techniques have been used to reduce the problems that lack of co- 2286 herence poses for users. These techniques have not been clearly 2287 defined by earlier specifications and it is often unclear what is 2288 valid or invalid client behavior. 2290 NFS version 4 uses many techniques similar to those that have been 2291 used in previous versions of NFS. It does not provide distributed 2292 cache coherence, but it defines a more limited set of caching 2293 guarantees to allow locks and share reservation to be used without 2294 destructive interference from client-side caching. 2296 In addition, version 4 introduces a delegation mechanism which allows 2297 many decisions normally made by the server to be made locally by 2298 clients. This provides efficient support of the common cases where 2299 sharing is infrequent or where sharing is read-only. 2301 9.1. Performance Challenges for Client-Side Caching 2303 Caching techniques used in previous versions of NFS have been 2304 successful in providing good performance. However, several scala- 2305 bility challenges can arise when those techniques are used with very 2306 large numbers of clients, particularly when those clients are 2307 geographically distributed, increasing the latency for cache 2308 revalidation requests. 2310 When latencies are large, repeated cache validation requests at open 2311 time, which NFS-v2 and NFS-v3 clients typically do, can have serious 2312 performance drawbacks. A common case is one in which a file is only 2313 accessed by a single client. Sharing is infrequent. 2315 In this case, repeated reference to the server to find that no 2316 conflicts exist, is expensive. A better option is to allow a client 2317 repeatedly opening a file to do so without reference to the server, 2318 until potentially conflicting operations from another client actually 2319 occur. 2321 A similar situation arises in connection with file locking. Sending 2322 file lock and unlock requests to the server as well as the I/O 2323 requests necessary to make data caching consistent with the locking 2324 semantics (see the section "Data Caching and File Locking") can 2325 severely limit performance. When locking is used to provide pro- 2327 Draft Protocol Specification NFS version 4 October 1999 2329 tection against infrequent conflicts, a large penalty will be paid, 2330 which may discourage the use of locking. 2332 In NFS Version 4, more aggressive caching strategies are designed: 2334 o To be compatible with a large range of server semantics. 2336 o Provide the same caching benefits as previous versions of NFS 2337 when unable to provide the more aggressive model. 2339 o Requirements for aggressive caching are organized so that a 2340 large portion of the benefit can be obtained even when not all 2341 of the requirements can be met. 2343 The appropriate requirements for the server are discussed in later 2344 sections in which specific forms of caching are dealt with. (see 2345 Section "Open Delegation"). 2347 NOTE: [[This discussion of proxy caching assumes that the a 2348 proxy server appears to the (real) server as an ordinary 2349 client. Should there be a proposal for non-transparent 2350 proxy server support (Mike Eisler's proxy model 2), this 2351 can be modified.]] 2353 9.2. Proxy Caching 2355 Proxy caching is a useful technique to reduce latency and avoid 2356 server overload when a large number of geographically distributed 2357 clients share data. The proxy cache allows many requests to be 2358 satisfied by a local server, reducing bandwidth and latencies 2359 associated with accessing the primary server. 2361 If NFS version 4 were to limit itself to the caching approaches used 2362 in NFS v2 and NFS v3, a large number of the requests which a proxy 2363 server would receive would result in corresponding requests to the 2364 distant server: 2366 o All OPEN and CLOSE requests 2368 o WRITE requests necessary to flush out dirty data before all file 2369 close operations. 2371 o All LOCK and UNLOCK requests. 2373 Draft Protocol Specification NFS version 4 October 1999 2375 o READ and WRITE requests which must go to the server because 2376 locks are held or being released. 2378 o All directory modification requests (e.g. CREATE, REMOVE, etc.) 2380 o All SETATTR requests 2382 o Many other requests because of cache entry staleness 2384 Maintaining distributed caches allowing authoritative decisions to be 2385 made locally is difficult, in the general case. However, there are 2386 many situations in which access patterns allow such decisions to be 2387 delegated opportunistically to particular clients (such as proxy 2388 servers) avoiding a great deal of unnecessary communication. This is 2389 of particular importance when scaling to very large numbers of 2390 clients. 2392 9.3. Delegation and Callbacks 2394 Recallable delegation of server responsibilities for a file to a 2395 client (which may include proxy servers) improves performance by 2396 avoiding repeated requests to the server in the absence of 2397 interclient conflict. A server recalls delegated responsibilities, 2398 using a callback rpc from the server to the client, when another 2399 client engages in sharing of a delegated file. 2401 A delegation is passed from the server to the client, specifying the 2402 object for which the delegation is being done and type of delegation. 2403 There are different types of delegations but each contains a stateid 2404 to be used to represent the delegation when performing operations 2405 that depend on the delegation. This stateid is similar to those 2406 associated with locks and share reservations but differs in that the 2407 stateid for a delegation is associated with a clientid and may be 2408 used on behalf of all the nfs_lockowner's for the given client. A 2409 delegation is made to the client as a whole and not to any specific 2410 process within it. 2412 Because callback rpc's may not work in all environments (due to 2413 firewalls, for example), correct operation does not depend on them. 2414 Preliminary testing of callback functionality by means of a CB_NULL 2415 request determines whether callbacks can be supported. The CB_NULL 2416 request checks the continuity of the callback path. A server makes a 2417 preliminary assessment of callback availability to a given client and 2418 avoids delegating responsibilities until it has determined that 2419 callbacks are supported. Because client requests for delegation are 2420 always conditional upon the absence of conflicting access, clients 2422 Draft Protocol Specification NFS version 4 October 1999 2424 can not assume that a request for delegation will be granted, and 2425 must always be prepared for denial. 2427 Once granted, a delegation behaves in most ways like a lock. There 2428 is an associated lease that is subject to renewal together with all 2429 of the other leases held by that client. 2431 Unlike locks, a request to a delegated file from a second client will 2432 cause the server to recall a delegation through a callback. 2434 On recall, the client holding the delegation must flush modified 2435 state (such as modified data) to the server and return the 2436 delegation. The conflicting request will not be responded to until 2437 the recall is complete, either by the return of the delegation or by 2438 the server timing out the recall and revoking the delegation. 2439 Following recall, the server has the information necessary to grant 2440 or deny second client's request. 2442 Since recalling a delegation may involve the flushing of substantial 2443 state to the server, the server should allow a time to complete the 2444 recall substantially longer than for a typical single RPC. The 2445 server may also extend the time allowed if it can determine that 2446 state is being diligently flushed by the client. However, the time 2447 to complete the recall should not be unbounded. 2449 For example, when responsibility to mediate opens on a given file is 2450 delegated to a client (see the section "Open Delegation"), the server 2451 will not know what opens are in effect on the client and thus will be 2452 unable to determine whether the access and deny state for the file 2453 allows any particular open until the delegation has been returned. 2455 Client failure or a network partition can result in failure to 2456 respond to a recall callback. The server will revoke the delegation, 2457 rendering any modified state still on the client useless. 2459 9.3.1. Delegation Recovery 2461 There are three situations that delegation recovery must deal with: 2463 o Client reboot 2465 o Server reboot 2467 o Network partition (full or callback-only) 2469 Draft Protocol Specification NFS version 4 October 1999 2471 In the even of a client reboot, the failure to renew leases will 2472 result in the revocation of record locks and share reservations. 2473 Delegations, however, may treated a bit differently. 2475 Because data associated with some delegations may be written to 2476 stable storage on the client and because a delegation held by a proxy 2477 server may be further delegated to its client in turn whereupon the 2478 proxy server may reboot, there will be situations in which 2479 delegations will need to be re-established after a client (which 2480 includes a proxy server) reboots. 2482 To accommodate such situations, the server may, after leases expire, 2483 force requests that conflict with existing delegations to wait for a 2484 longer period of time. This is consistent with the fact that recall, 2485 including the time necessary to flush modified state to the server 2486 and return the delegation, may take significant time. This longer 2487 interval would allow clients which reboot to consult stable storage 2488 and request the reclamation of delegations which have not been timed 2489 out using this longer interval. For open delegations, such 2490 delegations are reclaimed using OPEN with a claim type of 2491 CLAIM_DELEGATE_PREV. (See the Sections on "Data Caching and 2492 Revocation" and "Procedure 17: OPEN" for discussion of open 2493 delegation and the details of OPEN respectively). 2495 When the server reboots, delegations are reclaimed (using OPEN with 2496 CLAIM_DELEGATE_PREV) in a similar fashion to record locks and share 2497 reservations. However, there is a slight semantic difference. 2498 Normally, the server decides that a delegation should not be granted, 2499 it performs the requested action (e.g. OPEN) without granting any 2500 delegation. When this happens as part of reclaim, the server grants 2501 the delegation but marks it specially so that the client treats the 2502 delegation as having been granted but recalled by the server so that 2503 it then has the duty to write all modified state to the server and 2504 then return the delegation. This handling of delegation reclaim 2505 reconciles three principles of NFS Version 4: 2507 o That upon reclaim, a client faithfully reporting resources 2508 assigned to it by an earlier server instance, must be granted 2509 those resources. 2511 o That the server has untrammeled authority to determine whether 2512 delegations are to be granted and, once granted, whether they 2513 are to be continued. 2515 o That the use of callbacks is not to be depended upon until the 2516 client has proved its ability to receive them. 2518 Draft Protocol Specification NFS version 4 October 1999 2520 When a network partition occurs, delegations, like locks and share 2521 reservations will be subject to freeing when the lease renewal period 2522 expires, although the server will normally extend the period in which 2523 conflicting requests are held off in the case of delegations. 2524 Eventually, however, the occurrence of a conflicting request from 2525 another client will cause revocation of the delegation. A blockage 2526 of the callback (e.g. by later network configuration change) will 2527 have the same effect. A recall request will fail and revocation of 2528 the delegation will result. 2530 A client normally finds out about revocation of a delegation when it 2531 uses a stateid associated with a delegation and receives the error 2532 NFS4ERR_EXPIRED. It also may find out about delegation revocation 2533 after a client reboot when it attempts to reclaim a delegation and 2534 receives that same error. Note that in the case of a revoked write 2535 open delegation, there are issues because data may have been modified 2536 by the client whose delegation is revoked and separately by other 2537 clients. See the section "Revocation Recovery for Write Open 2538 Delegation" for a discussion of such issues. Note also that when 2539 delegations are revoked information about the revoked delegation will 2540 be written by the server to stable storage (as described in section 2541 7.5) to deal with the case in which a server reboots after revoking a 2542 delegation but before revoked delegate find out about the revocation. 2544 9.4. Data Caching 2546 When programs share access to a set of files they need to be 2547 implemented so as to take account of the possibility of conflicting 2548 access by another program. This is true whether the programs in 2549 question are on different hosts or reside on the same host. 2551 Share reservations and record locks are the facilities that NFS v4 2552 provides to allow programs to co-ordinate access by providing mutual 2553 exclusion facilities. NFS v4 data caching must be implemented so 2554 that it does not vitiate the assumptions that those using these 2555 facilities depend on. 2557 9.4.1. Data Caching and OPENs 2559 In order to avoid invalidating the sharing assumptions that 2560 applications rely on, NFS v4 clients should not provide cached data 2561 to applications or modify it on behalf of an application when it 2562 would not be valid to obtain/modify that same data via a READ or 2563 WRITE rpc. 2565 Draft Protocol Specification NFS version 4 October 1999 2567 Further, in the absence of open delegation (see the Section "Open 2568 delegation"), two further rules apply. These rules are obeyed in 2569 practice by many NFS v2 and NFS v3 clients. 2571 o The first rule is that cached data present on a client must be 2572 revalidated after doing an OPEN, to make sure that the data for 2573 the file in question, is still validly reflected in the client's 2574 cache. This must be done at least when a client open includes 2575 DENY=WRITE or BOTH, terminating a period in which other clients 2576 may have had the opportunity to open the file with WRITE access. 2577 Clients may choose to do the revalidation more often (i.e. on 2578 opens specifying DENY=NONE) to parallel NFS v3 practice for the 2579 benefit of users assuming this degree of cache revalidation. 2581 o The second rule, complementary to the first, is that modified 2582 data must be flushed to the server before closing a file opened 2583 for write. If this rule is not adhered to, the revalidation 2584 done after client OPEN's cannot achieve its purpose. This data 2585 must be committed to stable storage before the CLOSE is done 2586 since retransmission of the data after a server reboot might not 2587 be possible, once the file is closed. 2589 9.4.2. Data Caching and File Locking 2591 When users do not use share reservations to exclude inconsistent 2592 access, but use file locking instead, there is an analogous set of 2593 constraints that apply to client side data caching. These rules are 2594 effective only if file locking is used in a way which is congruent 2595 with the actual IO operations being done, as opposed to being used in 2596 a purely conventional way. For example, it is possible to manipulate 2597 a 2MB file, dividing the file into two 1MB regions, and using a lock 2598 for write on byte 0 of the file to represent the right to do IO to 2599 the first region and a lock for write to byte 1 of the file to 2600 represent the right to do IO on the second region. As long as all 2601 applications manipulating the file obey this convention, they will 2602 work on a local file system, but they may not work on NFS v4 unless 2603 clients refrain from data caching. 2605 The first rule is that when a client locks a region, it must 2606 revalidate its data cache if it has any cached data in the region 2607 newly locked and invalidate it if the change attribute shows that the 2608 file may have been written since that data was obtained. (A client 2609 might choose to invalidate all of non-modified cached data that it 2610 has, but invalidating all of the data in the newly locked region is 2611 necessary for correct operation). 2613 Draft Protocol Specification NFS version 4 October 1999 2615 The second rule is that before releasing a write lock for a region, 2616 all modified data for that region must be flushed to the server 2617 (although not necessarily to disk). 2619 Note that flushing data to the server and the invalidation of cached 2620 data must reflect the actual byte ranges locked or unlocked. 2621 Rounding these up or down to reflect client cache block boundaries 2622 will cause problems if not carefully done. For example, writing a 2623 modified block when only half of that block is within an area being 2624 unlocked may cause invalid modification to the region outside the 2625 unlocked area which may be part of a region locked by another client. 2626 Clients can avoid this situation by synchronously performing portions 2627 of write operations that overlap that portion (initial or final) that 2628 is not a full block. Similarly, invalidating a locked area which is 2629 not an integral number of full buffer blocks would require the client 2630 to read one or two partial blocks from the server if the revalidation 2631 procedure shows that the data which the client possesses may not be 2632 valid. 2634 Writes required to flush data before unlocking must be done to stable 2635 storage, either by doing synchronous writes or a COMMIT as part of 2636 the flush operation. The is so because retransmission of the 2637 modified data after a server reboot might conflict with a lock held 2638 by another client. 2640 Clients may choose to accommodate programs using record locking in 2641 non-standard ways (e.g. using a record lock as a global semaphore), 2642 by flushing to the server more data upon an UNLOCK than is covered by 2643 the locked range, possibly including modified data in other files. 2644 Any client doing so must ensure that for any file in which all data 2645 written is to properly locked areas, no piece of data be written to 2646 the server which is not within the locked area. 2648 9.4.3. Data Caching and Mandatory File Locking 2650 Client side data caching needs to respect mandatory file locking when 2651 this is in effect. The presence of mandatory file locking for a 2652 given file is indicated in the result flags for an OPEN. When there 2653 is a read or write for a file for which mandatory locking is in 2654 effect, the client must check if it holds an appropriate lock for the 2655 range of bytes being read or written. If it does, it may satisfy the 2656 request using client side caching, just as for any other read or 2657 write. If such a lock is not held, the read or write cannot be 2658 satisfied by caching but must be sent to the server. When a request 2659 partially overlaps a locked area, the request should be broken up 2660 into multiple pieces with each region (locked or not) treated 2662 Draft Protocol Specification NFS version 4 October 1999 2664 appropriately. 2666 9.4.4. Data Caching and File Identity 2668 When clients cache data, data needs to organized according to the the 2669 file system object to which the data belongs. For NFS v3 clients, 2670 the typical practice has been to assume (for this purpose) that 2671 distinct handles represent distinct filesystem objects (even though 2672 in some unusual cases this has not been the case) and that the data 2673 cache may be maintained on the this basis. 2675 In NFS v4, we have the prospect (due to pathname based handles) of 2676 more significant deviations from a one-filehandle-per-object model. 2677 This requires some method by which clients may reliably determine 2678 whether two filehandles designate the same object. If they were to 2679 simply assume that all distinct filehandles denoted distinct objects 2680 and proceeded to do data caching on that basis, caching 2681 inconsistencies would arise between the distinct client side objects 2682 which mapped to the same server side object. While it is true that 2683 such inconsistencies would be similar to those typically seen by 2684 programs running on multiple clients (apart from this issue), these 2685 inconsistencies would not be expected an NFS v3 clients not sharing 2686 files with any other client. The appearance of such inconsistencies 2687 would be a definite problem inhibiting transition from NFS v3 to NFS 2688 v4 and so must be avoided. 2690 The following procedure allows an NFS v4 client to determine (for the 2691 purposes of data caching) whether two distinct filehandles denote the 2692 same server side object: 2694 o If GETATTR directed to the two handles in question have 2695 different values of fsid.major or fsid.minor, then they are 2696 distinct objects. 2698 o If GETATTR for any file on the fsid (major and minor) to which 2699 the two handles belong and unique_handles is TRUE, then the two 2700 objects are distinct. 2702 o If GETATTR directed to the two handles does not return the 2703 fileid attribute for one or both of the handles, then the it 2704 cannot be determined whether the two objects are the same and so 2705 operations which depend on that knowledge (e.g. client side data 2706 caching) cannot be done reliably. 2708 o If the two GETATTR's return different values for the fileid 2710 Draft Protocol Specification NFS version 4 October 1999 2712 attribute, then they are distinct objects. 2714 o Otherwise they are the same object. 2716 9.5. Open Delegation 2718 When a file is being opened, the server may delegate further handling 2719 of opens and closes for that file to the opening client. Any such 2720 delegation is recallable, since the circumstances that occasioned it 2721 are subject to change. In particular, the server may receive a 2722 conflicting OPEN from another client, which obliges it to recall the 2723 delegation before deciding whether the OPEN may be granted. Granting 2724 a delegation request is up to the server and it may deny all such 2725 requests. The following is a typical set of conditions that servers 2726 might use in deciding whether open should be delegated: 2728 o The client must be able to respond to callbacks (as evidenced by 2729 responding to previous CB_NULL requests). 2731 o The client must not have failed to respond properly to previous 2732 recalls. 2734 o There must be no current open conflicting with the requested 2735 delegation. 2737 o There should be no current delegation that conflicts with the 2738 delegation being requested. 2740 o The probability of future conflicting open requests should be 2741 low based on the recent history of the file. 2743 o The existence of any server specific semantics of OPEN/CLOSE 2744 that would make the required handling incompatible with the 2745 prescribed handling that the delegated client would apply (see 2746 below). 2748 There are two types of open delegations, read and write. A read open 2749 delegation allows a client to handle, on its own, requests to open a 2750 file for reading that do not deny read access to others. Multiple 2751 read open delegations may be outstanding simultaneously and do not 2752 conflict. A write open delegation allows the client to handle on its 2753 own all opens. Only one write open delegation may exist for a given 2754 file at a given time and it is inconsistent with any read open 2756 Draft Protocol Specification NFS version 4 October 1999 2758 delegations. 2760 When a client has a read open delegation, it may not make any changes 2761 to the contents or attributes of the file but it is assured that no 2762 other client may do so. When a client has a write open delegation it 2763 may modify the file data as it wishes secure in the knowledge that no 2764 other client is accessing the file's data. The client holding a 2765 write delegation may only affect file attributes which are intimately 2766 connected with the file data: length, modify_time, change. 2768 When a client has an open delegation, it does not send OPEN's, or 2769 CLOSE's to the server but updates the appropriate status internally. 2770 For a read open delegation, opens that cannot be handled locally 2771 (opens for write or that deny read access) must go to the server. 2773 When an open delegation is requested and granted, the response to the 2774 OPEN contains an open delegation structure which specifies, the type 2775 of delegation (read or write), space limitation information to 2776 control flushing of data on close (write open delegation only, see 2777 the Section "Open Delegation and Data Caching"), an nfsace4 2778 specifying read and write permissions and a stateid to represent the 2779 delegation when doing IO. This stateid is separate and distinct from 2780 the stateid for the OPEN proper, which, unlike the delegation 2781 stateid, is associated with a particular nfs_lockowner, and will 2782 continue to be valid after the delegation is recalled, if the file 2783 remains open. 2785 When an internal request (or a request by one of a proxy server's 2786 clients) is made to open a file when open delegation is in effect, it 2787 will be accepted or rejected solely on the basis of the following 2788 conditions. Any requirement for other checks to be made by the 2789 delegate, should result in open delegation being denied so that the 2790 checks can be made by the server itself. 2792 o The access and deny bits for the request and the file as 2793 described in Section 7.7, Share reservations 2795 o The read and write permissions as determined below. 2797 The nfsace4 passed with delegation can be used to avoid frequent 2798 ACCESS calls. The permission check should be as follows: 2800 o If the nfsace4 indicates that the open may be done, then it 2801 should be granted, without reference to the server. 2803 Draft Protocol Specification NFS version 4 October 1999 2805 o If the nfsace4 indicates that the open may not be done, then an 2806 ACCESS request must be made to the server to obtain the 2807 definitive answer. 2809 The server may thus return an nfsace4 that is more restrictive than 2810 the actual ACL of the file, including one that specifies denial of 2811 all access. Note that some common practices like mapping root to 2812 nobody may make it incorrect to send the actual ACL of the file in 2813 some cases. 2815 The use of delegation together with various other forms of caching 2816 creates the possibility that no server authentication will ever be 2817 performed on a given user since all of his requests might be 2818 satisfied locally. Where the client is depending of the server for 2819 authentication, it should make sure that some authentication (via an 2820 ACCESS call) happens for each user, even if an ACCESS call would not 2821 otherwise be required. The server may enforce frequent 2822 authentication by returning an nfsace4 denying all access with every 2823 open delegation. 2825 9.5.1. Open Delegation and Data Caching 2827 Open delegation allows much of the message overhead associated with 2828 opening and close files to be eliminated. This is also the case for 2829 a proxy server to which an open delegation was made but which did not 2830 pass the delegation on. In either case, an open when an open 2831 delegation was in effect would not require that a validation message 2832 be sent to the server. The continued endurance of the read-open- 2833 delegation provides a guarantee that no open for write and thus no 2834 write has occurred. Similarly, when closing a file opened for write, 2835 if write open delegation is in effect, the data written does not have 2836 to be flushed to the server until the open delegation is recalled. 2837 The continued endurance of the open delegation provides a guarantee 2838 that no open and thus no read or write has been done by another 2839 client. 2841 For the purposes of open delegation, IO done without an OPEN (via 2842 special stateid's consisting of all zero bits or all one bits) are 2843 treated as the functional equivalent of a corresponding type of open. 2844 Thus, such READ's or WRITE's done by another client need will provoke 2845 recall of a write open delegation, will any such WRITE will provoke 2846 recall of a read open delegation. 2848 In order to maintain current semantics in which the non-availability 2849 of storage to hold a file written by an NFS client is guaranteed to 2851 Draft Protocol Specification NFS version 4 October 1999 2853 be determined at or before the associated close operation, the 2854 avoidance by the client of the requirement to flush data to the 2855 server on close, is limited to cases in which the client and server 2856 together can determine in advance that the required space will be 2857 available. The server specifies one of a number of limiting 2858 conditions, either a limit on the size of the file or a limit on the 2859 number of modified blocks using a blocksize supplied by the server. 2860 Based on implementation experience, changes in the form of these 2861 conditions may be made or new types of limiting conditions defined. 2862 Whatever the form of condition used, it us up to the server to ensure 2863 that any set of writes, no matter how arranged that meets the 2864 specified condition will ever encounter a lack of disk space 2865 availability when the modified data is allowed to remain on the 2866 client unflushed to the server past the point of close. The server 2867 must make sure that the maximum possible amount of storage is 2868 reserved so that all outstanding delegations together meet that 2869 condition, and to recall delegations appropriately to maintain that 2870 invariant. When a server implements quotas, it should also be 2871 careful that it does not invalidate its quota invariants when 2872 granting write open delegation. When a user is near a quota limit, 2873 this may result in write open delegations granted with very 2874 restrictive space limitation conditions or those which always force 2875 modified data to be flushed to the server on close. 2877 When authentication considerations make flushing of modified data to 2878 the server after the close problematic (after the last close, the 2879 user may have logged off and unexpired local credentials may not 2880 exist), the client may need to take special care to ensure that local 2881 unexpired credentials will in fact be available, either by tracking 2882 the expiration time of credentials and flushing data well in advance 2883 of their expiration, or by making private copies of credentials to 2884 assure their availability when needed. 2886 9.5.2. Open Delegation and File Locks 2888 When a client holds a write-open-delegation, lock operations, 2889 including those required by mandatory file locking are performed 2890 locally since the delegation implies that there can be no conflicting 2891 locks. On a similar basis, all of the revalidations that would 2892 normally be associated with obtaining locks and the flushing of data 2893 which would attend the releasing of locks for write need not be done. 2895 9.5.3. Recall of Open Delegation 2897 Draft Protocol Specification NFS version 4 October 1999 2899 The following events necessitate recall of an open delegation: 2901 o Potentially conflicting OPEN request (or IO done with "special" 2902 stateid) 2904 o SETATTR issued by another client 2906 o REMOVE request for the file in question 2908 o RENAME request for the file in question as either source or 2909 target of the RENAME 2911 NOTE: [[The following are necessary unless the spec is 2912 cleaned up to disallow LOCK's and IO operations without a 2913 corresponding OPEN.]] 2915 o LOCK request by another client. 2917 o IO operation done with "special" stateid by another client. 2919 Whether a RENAME of a directory in the path leading to the file 2920 results in recall of an open delegation depends on the semantics of 2921 the server file system. If that filesystem denies such RENAME's when 2922 a file is open, the recall must be performed to determine whether the 2923 file in question is, in fact, open. 2925 In addition to the situations above, the server may choose to recall 2926 open delegations at any time if resource constraints make it 2927 advisable to do so. Clients should always be prepared for the 2928 possibility of recall. 2930 Special handling is needed for a GETATTR which occurs when a write 2931 open delegation is in effect. In this case, the client holding the 2932 delegation needs to be interrogated, using a CB_GETATTR callback, if 2933 the GETATTR attribute bits include any of the attributes that a write 2934 open delegate may modify (length, modify time, change). 2936 When a client receives a recall for an open delegation, it needs to 2937 update state on the server before returning the delegation. These 2938 same updates must be done whenever a client chooses to return a 2939 delegation voluntarily. The following items of state need to be 2940 dealt with: 2942 Draft Protocol Specification NFS version 4 October 1999 2944 o If the open file associated with the OPEN which delivered the 2945 delegation to the client is no longer open, then a CLOSE must be 2946 done to the server, if this has not been done previously. 2948 o If there are other opens extant for that file, then OPEN 2949 operations must be done to update the server and obtain the 2950 stateid's to be used subsequently, given that the delegation 2951 stateid will no longer be valid. Such OPEN's are done using a 2952 claim type of CLAIM_DELEGATE_CUR so that the delegation stateid 2953 can be presented to the server to establish the client's right 2954 to perform this OPEN. (See the section "Procedure 17: OPEN" for 2955 details). 2957 o If there are locks which have been granted (write open 2958 delegation case only), then these need to be performed to the 2959 server. 2961 In the case of a write open delegation, if the file in question is 2962 not opened for write at the time of recall, then any modified data 2963 for the file needs to be flushed to the server, as it would have been 2964 flushed when the file was closed, had the write open delegation not 2965 been in effect. The possibility of truncation on the client means 2966 that the following needs to be done: 2968 o If a file truncate has been done on the client (as part of an 2969 OPEN UNCHECKED, for example), and this has not yet been 2970 propagated to the server (it must be before allowing any new 2971 data to be written to the server), it must be done as part of 2972 recall, again before writing modified data to the server. 2974 o Any modified data for the file needs to be flushed to the the 2975 server. 2977 In the case of write open delegation, file locking imposes some 2978 additional requirements. The flushing of any modified data in any 2979 area for which a write lock was released while the write open 2980 delegation was in effect is what is required to precisely maintain 2981 the associated invariant. However, because the write open delegation 2982 implies no other locking by other clients, a simpler implementation 2983 is to flush all modified data for the file (as described just above) 2984 if any write lock has been released while the write open delegation 2985 was in effect. 2987 Draft Protocol Specification NFS version 4 October 1999 2989 9.5.4. Delegation Revocation 2991 When a delegation is revoked, if there are associated opens on the 2992 client, the processes holding these opens need to be notified, 2993 normally by returning errors whenever IO operations or a close is 2994 attempted on that open file. 2996 When an open delegation is revoked, if no opens are present on the 2997 client, then no error needs to be reported, unless there is modified 2998 data present on the client. In this case, the user will have to be 2999 notified, since there may not be an active application to get an 3000 error status. (See the section "Revocation Recovery for Write Open 3001 Delegation" for more details). 3003 9.6. Data Caching and Revocation 3005 When locks (including delegations) are revoked, the assumptions upon 3006 which successful caching depend, are no longer guaranteed. Therefore 3007 the client, in addition to notifying the owner of a record lock or 3008 share reservation, and processes holding opens for the delegation, 3009 needs to remove all data for the file from its cache. In the case of 3010 modified data, it must be removed from the client's cache without 3011 being written to the server. 3013 Notification to the lock owner will in many cases consist of simply 3014 returning an error on the next (and all subsequent) IO to the open 3015 file or on the close. Where the client API make such notification 3016 impossible (because errors for certain operations may not be 3017 returned), more drastic action such as signals or process termination 3018 may be appropriate since an invariant that an application depends on 3019 may be violated. Depending on how errors are typically treated on 3020 the client operating system, further levels of notification including 3021 logging, console messages, and GUI pop-up's may be in order. 3023 9.6.1. Revocation Recovery for Write Open Delegation 3025 Revocation recovery for a write open delegation poses the issue in 3026 that there may be modified data in the client cache while the file is 3027 not open. In this situation, any client which does not flush 3028 modified data to the server on each close must make sure that the 3029 user receives appropriate notification of the failure. Since such 3030 situations may require human action to correct problems, notification 3031 schemes in which the appropriate user or administrator is notified 3033 Draft Protocol Specification NFS version 4 October 1999 3035 may be necessary. Logging and console messages are typical examples. 3037 If there is modified data on the client, it must not be flushed 3038 normally to the server. A client may attempt to provide a copy of 3039 the file data as modified during the delegation under a different 3040 name, to ease recovery. Unless the client can determine that the 3041 file was has not modified by any other client, this technique is 3042 limited to situations in which a client has a complete cached copy of 3043 the file in question. Use of such a technique may be limited to 3044 files under a certain size or may only be used when sufficient disk 3045 space is guaranteed available within the target file system and when 3046 the client has sufficient buffering resources to keep the cached copy 3047 available until it is properly stored to the target file system. 3049 9.7. Attribute Caching 3051 First note that when attributes are discussed here, extended or named 3052 attributes are not included. Individual named attributes are 3053 analogous to files and caching of the data for these needs to be 3054 handled just as data caching is for ordinary files. Similarly, LOOKUP 3055 results from an OPENATTR directory are to be cached on the same basis 3056 as any other pathnames and similarly for directory contents. 3058 Clients may cache file attributes obtained from the server and use 3059 them to avoid subsequent GETATTR requests. Such caching is write 3060 through in that modification to file attributes is always done by 3061 means of requests to the server and should not be done locally and 3062 cached, the exception being modifications to attributes that are 3063 intimately connected with data caching. Thus, extending a file by 3064 writing data to the local data cache is reflected immediately in the 3065 length as seen on the client without this change being immediately 3066 reflected on the server. Normally such changes are not propagated 3067 directly to the server, but when the modified data is flushed to the 3068 server, analogous attribute changes are made on the server. When 3069 open delegation is in effect, the modified attributes may be returned 3070 to the server in the response to a CB_RECALL call. 3072 The result of local caching of attributes is that the attribute 3073 caches maintained on individual clients will not be coherent. Changes 3074 made in one order on the server may be seen in a different order on 3075 one client and in a third order on a different client. 3077 Given that typical file API's do not provide means to atomically 3078 modify or interrogate attributes for multiple files at the same time, 3079 the undesirable effects of these incoherencies have proved 3080 manageable, if the following rules, derived from the practice of 3082 Draft Protocol Specification NFS version 4 October 1999 3084 NFSv3 implementations are followed: 3086 o All attributes for a given file (per-fsid attributes excepted) 3087 are cached as a unit so that no non-serializability can arise 3088 within the context of a single file. 3090 o A bound is maintained on how long a client cache entry can be 3091 kept without being refreshed from the server. 3093 o When performing any operation that changes attributes on the 3094 server, including directory operations that due so indirectly, 3095 updated attributes would be fetched as part of the associated 3096 rpc, using a GETATTR following the operation in question, which 3097 the results of the GETATTR used to update the client's attribute 3098 cache. 3100 Note that if the full set of attributes to be cached is requested by 3101 READDIR, the results can be cached by the client on the same basis as 3102 attributes obtained GETATTR. 3104 A client may validate its cached version of attributes for a file by 3105 fetching only the change attribute and assuming that if the change 3106 attribute has the same value as it did when the attributes were 3107 cached, then no attributes have changed, with the possible exception 3108 of access_time. 3110 9.8. Name Caching 3112 The results of LOOKUP and READDIR operations may be cached to avoid 3113 the cost of subsequent LOOKUP operations. Just as in the case 3114 attribute caching, inconsistencies may arise among the various client 3115 caches. To mitigate the effects of these inconsistencies, given the 3116 context of typical file API's, the following rules should be adhered 3117 to: 3119 o The results of unsuccessful LOOKUP's should not cached, unless 3120 they are specifically reverified at the point of use. 3122 o A bound is maintained on how long a client name cache entry can 3123 be kept without verifying that the entry in question has not 3124 been made invalid by a directory change operation performed by 3125 another client. 3127 Draft Protocol Specification NFS version 4 October 1999 3129 When a client is not making changes to a directory for which there 3130 exist name cache entries, it needs to periodically fetch attributes 3131 for that directory to make sure that it is not changing. After 3132 determining that no change that has occurred, the expiration time for 3133 the associated name cache entries may be updated to be the current 3134 time plus the name cache staleness bound. 3136 When a client is making changes to a given directory, it needs to 3137 determine whether there have been changes made to the directory by 3138 other clients. It does this using the change attribute as reported 3139 before and after the directory operation in the associated wcc4_info 3140 returned on that operation. When the server is able to report these 3141 values atomically with respect to the directory operation, which the 3142 server indicates in the wcc4_info, comparison of the pre-operation 3143 change value with the change value which the client has in his cache 3144 determines whether there has been a change by another client, 3145 necessitating a purge of name cache associated with the directory. 3146 If there has been no such change, the name cache can be updated on 3147 the client to reflect the directory operation and the associated 3148 timeout extended. The post-operation change value needs to be saved 3149 as the basis for future wcc4_info comparisons. 3151 Name caching requires that the client revalidate cached data by 3152 comparing the change attribute for a directory when the name item was 3153 cached. This requires that any changes in the contents of a 3154 directory be visible as a changed value for the change attribute of 3155 the directory. Proper use of wcc4_info, when a client makes a change 3156 to a directory, requires that reporting of the pre-operation and 3157 post-operation change attribute values are in fact atomic with the 3158 actual directory change. When the server cannot reliably report 3159 before and after values atomically with respect to the directory 3160 operation, the server indicates that in the wcc4_info and the client 3161 should not assume that other clients have not changed the directory. 3163 9.9. Directory Caching 3165 The results of READDIR operations may be used to avoid subsequent 3166 READDIR operations. Just as in the cases of attribute and name 3167 caching, this may result in inconsistencies among the various client 3168 caches. To mitigate the effects of these inconsistencies, given the 3169 context of typical file API's, the following rules should be adhered 3170 to: 3172 o Cached READDIR information for a directory which is not obtained 3173 in a single READDIR operation must always be a consistent 3175 Draft Protocol Specification NFS version 4 October 1999 3177 snapshot of directory contents as evidenced by a GETATTR before 3178 the first and after the last of READDIR's which contribute. 3180 o A bound is maintained on the amount of time that a directory 3181 cache entry may be kept on the client without revalidation. 3183 The revalidation technique parallels that discussed in the case of 3184 name caching. When the client is not changing the directory in 3185 question, checking that the directory has not changed (by using 3186 GETATTR to obtain the change attribute) is adequate to extend the 3187 lifetime of the cache entry. When a client is modifying the 3188 directory, it needs to use the wcc4_info data to determine whether 3189 there are other clients who are modifying the directory, allowing it 3190 to update the directory cache to reflect its own changes if it is the 3191 only client making modifications. 3193 Directory caching requires that the client revalidate cached data by 3194 comparing the change attribute for a directory when the directory 3195 data was cached. This requires that any changes in the contents of a 3196 directory be visible as a changed value for the change attribute of 3197 the directory. Proper use of wcc4_info, when a client makes a change 3198 to a directory, require that reporting of the pre-operation and 3199 post-operation change attribute values are in fact atomic with the 3200 actual directory change. When the server cannot reliably report 3201 before and after values atomically with respect to the directory 3202 operation, the server indicates that in the wcc4_info and the client 3203 should not assume that other clients have not changed the directory. 3205 Draft Protocol Specification NFS version 4 October 1999 3207 10. Defined Error Numbers 3209 NFS error numbers are assigned to failed operations within a compound 3210 request. A compound request contains a number of NFS operations that 3211 have their results encoded in sequence in a compound reply. The 3212 results of successful operations will consist of an NFS4_OK status 3213 followed by the encoded results of the operation. If an NFS 3214 operation fails, an error status will be entered in the reply and the 3215 compound request will be terminated. 3217 A description of each defined error follows: 3219 NFS4_OK Indicates the operation completed successfully. 3221 NFS4ERR_PERM Not owner. The operation was not allowed 3222 because the caller is either not a privileged 3223 user (root) or not the owner of the target of 3224 the operation. 3226 NFS4ERR_NOENT No such file or directory. The file or 3227 directory name specified does not exist. 3229 NFS4ERR_IO I/O error. A hard error (for example, a disk 3230 error) occurred while processing the requested 3231 operation. 3233 NFS4ERR_NXIO I/O error. No such device or address. 3235 NFS4ERR_ACCES Permission denied. The caller does not have the 3236 correct permission to perform the requested 3237 operation. Contrast this with NFS4ERR_PERM, 3238 which restricts itself to owner or privileged 3239 user permission failures. 3241 NFS4ERR_EXIST File exists. The file specified already exists. 3243 NFS4ERR_XDEV Attempt to do a cross-device hard link. 3245 NFS4ERR_NODEV No such device. 3247 Draft Protocol Specification NFS version 4 October 1999 3249 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 3250 directory in a directory operation. 3252 NFS4ERR_ISDIR Is a directory. The caller specified a 3253 directory in a non-directory operation. 3255 NFS4ERR_INVAL Invalid argument or unsupported argument for an 3256 operation. Two examples are attempting a 3257 READLINK on an object other than a symbolic 3258 link or attempting to SETATTR a time field on a 3259 server that does not support this operation. 3261 NFS4ERR_FBIG File too large. The operation would have caused 3262 a file to grow beyond the server's limit. 3264 NFS4ERR_NOSPC No space left on device. The operation would 3265 have caused the server's file system to exceed 3266 its limit. 3268 NFS4ERR_ROFS Read-only file system. A modifying operation 3269 was attempted on a read-only file system. 3271 NFS4ERR_MLINK Too many hard links. 3273 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 3275 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 3276 was not empty. 3278 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The 3279 user's resource limit on the server has been 3280 exceeded. 3282 NFS4ERR_STALE Invalid file handle. The file handle given in 3283 the arguments was invalid. The file referred to 3284 by that file handle no longer exists or access 3285 to it has been revoked. 3287 Draft Protocol Specification NFS version 4 October 1999 3289 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 3290 internal consistency checks. 3292 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 3293 during a SETATTR operation. 3295 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 3297 NFS4ERR_NOTSUPP Operation is not supported. 3299 NFS4ERR_TOOSMALL Buffer or request is too small. 3301 NFS4ERR_SERVERFAULT An error occurred on the server which does not 3302 map to any of the legal NFS version 4 protocol 3303 error values. The client should translate this 3304 into an appropriate error. UNIX clients may 3305 choose to translate this to EIO. 3307 NFS4ERR_BADTYPE An attempt was made to create an object of a 3308 type not supported by the server. 3310 NFS4ERR_JUKEBOX The server initiated the request, but was not 3311 able to complete it in a timely fashion. The 3312 client should wait and then try the request 3313 with a new RPC transaction ID. For example, 3314 this error should be returned from a server 3315 that supports hierarchical storage and receives 3316 a request to process a file that has been 3317 migrated. In this case, the server should start 3318 the immigration process and respond to client 3319 with this error. 3321 NFS4ERR_SAME Returned if an NVERIFY operation shows that no 3322 attributes have changed. 3324 NFS4ERR_DENIED An attempt to lock a file is denied. Since 3325 this may be a temporary condition, the client 3326 is encouraged to retry the lock request (with 3327 exponential backoff of timeout) until the lock 3329 Draft Protocol Specification NFS version 4 October 1999 3331 is accepted. 3333 NFS4ERR_EXPIRED A lease has expired that is being used in the 3334 current procedure. 3336 NFS4ERR_LOCKED A read or write operation was attempted on a 3337 locked file. 3339 NFS4ERR_GRACE The server is in its recovery or grace period 3340 which should match the lease period of the 3341 server. 3343 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 3344 expired at the server. The client should 3345 attempt to recover the new file handle by 3346 traversing the server's file system name space. 3347 The file handle may have expired because the 3348 server has restarted, the file system object 3349 has been removed, or the file handle has been 3350 flushed from the server's internal mappings. 3352 NOTE: This error definition will need to be crisp and match 3353 the section describing the volatile file handles. 3355 NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share 3356 reservation has failed because of a share 3357 conflict. 3359 NFS4ERR_SAME This error is returned by the NVERIFY operation 3360 to signify that the attributes compared were 3361 the same as provided in the client's request. 3363 NFS4ERR_WRONGSEC The security mechanism being used by the client 3364 for the procedure does not match the server's 3365 security policy. The client should change the 3366 security mechanism being used and retry the 3367 operation. 3369 NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a 3371 Draft Protocol Specification NFS version 4 October 1999 3373 client id is already in use by another client. 3375 NFS4ERR_RESOURCE For the processing of the COMPOUND procedure, 3376 the server may exhaust available resources and 3377 can not continue processing procedures within 3378 the COMPOUND operation. This error will be 3379 returned from the server in those instances of 3380 resource exhaustion related to the processing 3381 of the COMPOUND procedure. 3383 NFS4ERR_MOVED The filesystem which contains the current 3384 filehandle object has been relocated or 3385 migrated to another server. The client may 3386 obtain the new filesystem location by obtaining 3387 the "fs_locations" attribute for the current 3388 filehandle. For further discussion, refer to 3389 the section "Filesystem Migration or 3390 Relocation". 3392 NFS4ERR_NOFILEHANDLE The logical current file handle value has not 3393 been set properly. This may be a result of a 3394 malformed COMPOUND operation (i.e. no PUTFH or 3395 PUTROOTFH before an operation that requires the 3396 current file handle be set). 3398 Draft Protocol Specification NFS version 4 October 1999 3400 11. NFS Version 4 Requests 3402 For the NFS program, version 4, there are two traditional RPC 3403 procedures: NULL and COMPOUND. All other operations for NFS version 3404 4 are defined in normal XDR/RPC syntax and semantics except that 3405 these operations are encapsulated within the COMPOUND request. This 3406 requires that the client combine one or more NFSv4 operations into a 3407 single request. 3409 The NFS4_CALLBACK program is used to provide server to client 3410 signaling and is constructed in a similar fashion as the NFS program. 3411 The procedures CB_NULL and CB_COMPOUND are defined in the same way as 3412 NULL and COMPOUND are within the NFS program. The CB_COMPOUND 3413 request also encapsulates the remaining operations of the 3414 NFS4_CALLBACK program. 3416 11.1. Compound Procedure 3418 These compound requests provide the opportunity for better 3419 performance on high latency networks. The client can avoid 3420 cumulative latency of multiple RPCs by combining multiple dependent 3421 operations into a single compound request. A compound op may provide 3422 for protocol simplification by allowing the client to combine basic 3423 procedures into a single request that is customized for the client's 3424 environment. 3426 The basics of the COMPOUND procedures construction is: 3428 +-----------+-----------+-----------+-- 3429 | op + args | op + args | op + args | 3430 +-----------+-----------+-----------+-- 3432 and the reply looks like this: 3434 +----------------+----------------+----------------+-- 3435 | code + results | code + results | code + results | 3436 +----------------+----------------+----------------+-- 3438 Where "code" is an indication of the success or failure of the 3439 operation including the opcode itself. 3441 11.2. Evaluation of a Compound Request 3443 The server will process the COMPOUND procedure by evaluating each of 3444 the operations within the COMPOUND request in order. Each component 3446 Draft Protocol Specification NFS version 4 October 1999 3448 operation consists of a 32 bit operation code, followed by the 3449 argument of length determined by the type of operation. The results 3450 of each operation are encoded in sequence into a reply buffer. The 3451 results of each operation are preceded by the opcode and a status 3452 code (normally zero). If an operation results in a non-zero status 3453 code, the status will be encoded and evaluation of the compound 3454 sequence will halt and the reply will be returned. 3456 There are no atomicity requirements for the procedures contained 3457 within the COMPOUND procedure. The operations being evaluated as 3458 part of a COMPOUND request may be evaluated simultaneously with other 3459 COMPOUND requests that the server receives. 3461 It is the client's responsibility for recovering from any partially 3462 completed compound request. 3464 Each operation assumes a "current" filehandle that is available as 3465 part of the execution context of the compound request. Operations 3466 may set, change, or return this filehandle. 3468 Draft Protocol Specification NFS version 4 October 1999 3470 12. NFS Version 4 Procedures 3472 12.1. Procedure 0: NULL - No Operation 3474 SYNOPSIS 3476 3478 ARGUMENT 3480 void; 3482 RESULT 3484 void; 3486 DESCRIPTION 3488 Standard ONCRPC NULL procedure. Void argument, void response. 3490 ERRORS 3492 None. 3494 Draft Protocol Specification NFS version 4 October 1999 3496 12.2. Procedure 1: COMPOUND - Compound Operations 3498 SYNOPSIS 3500 compoundargs -> compoundres 3502 ARGUMENT 3504 union opunion switch (unsigned opcode) { 3505 case : ; 3506 ... 3507 }; 3509 struct op { 3510 opunion ops; 3511 }; 3513 struct COMPOUND4args { 3514 utf8string tag; 3515 op oplist<>; 3516 }; 3518 RESULT 3520 struct COMPOUND4res { 3521 nfsstat4 status; 3522 utf8string tag; 3523 resultdata data<>; 3524 }; 3526 DESCRIPTION 3528 The COMPOUND procedure is used to combine one or more of the NFS 3529 procedures into a single RPC request. The main NFS RPC program has 3530 two main procedures: NULL and COMPOUND. All other procedures use 3531 the COMPOUND procedure as a wrapper. 3533 In the processing of the COMPOUND procedure, the server may find 3534 that it does not have the available resources to execute any or all 3535 of the procedures within the COMPOUND sequence. In this case, the 3536 error NFS4ERR_RESOURCE will be returned for the particular 3537 procedure within the COMPOUND operation where the resource 3538 exhaustion occurred. This assume that all previous procedures 3540 Draft Protocol Specification NFS version 4 October 1999 3542 within the COMPOUND sequence have been evaluated successfully. 3544 IMPLEMENTATION 3546 The COMPOUND procedure is used to combine individual procedures 3547 into a single RPC request. The server interprets each of the 3548 procedures in turn. If a procedure is executed by the server and 3549 the status of that procedure is NFS4_OK, then the next procedure in 3550 the COMPOUND procedure is executed. The server continues this 3551 process until there are no more procedures to be executed or one of 3552 the procedures has a status value other than NFS4_OK. 3554 Note that the definition of the "tag" in both the request and 3555 response are left to the implementor. It may be used to summarize 3556 the content of the compound request for the benefit of packet 3557 sniffers and engineers debugging implementations. 3559 ERRORS 3561 NFS4ERR_RESOURCE 3563 Draft Protocol Specification NFS version 4 October 1999 3565 12.2.1. Operation 2: ACCESS - Check Access Rights 3567 SYNOPSIS 3569 (cfh), accessreq -> supported, accessrights 3571 ARGUMENT 3573 const ACCESS4_READ = 0x0001; 3574 const ACCESS4_LOOKUP = 0x0002; 3575 const ACCESS4_MODIFY = 0x0004; 3576 const ACCESS4_EXTEND = 0x0008; 3577 const ACCESS4_DELETE = 0x0010; 3578 const ACCESS4_EXECUTE = 0x0020; 3580 struct ACCESS4args { 3581 /* CURRENT_FH: object */ 3582 uint32_t access; 3583 }; 3585 RESULT 3587 struct ACCESS4resok { 3588 uint32_t supported; 3589 uint32_t access; 3590 }; 3592 union ACCESS4res switch (nfsstat4 status) { 3593 case NFS4_OK: 3594 ACCESS4resok resok; 3595 default: 3596 void; 3597 }; 3599 DESCRIPTION 3601 ACCESS determines the access rights that a user, as identified by 3602 the credentials in the request, has with respect to a file system 3603 object. The client encodes the set of access rights that are to be 3604 checked in a bit mask. The server checks the permissions encoded 3605 in the bit mask. If a status of NFS4_OK is returned, two bit masks 3607 Draft Protocol Specification NFS version 4 October 1999 3609 are included in the response. The first represents the access 3610 rights for which the server can verify reliably for the user. The 3611 second represents the access rights available to the user for the 3612 filehandle provided. 3614 The results of this procedure are necessarily advisory in nature. 3615 That is, a return status of NFS4_OK and the appropriate bit set in 3616 the bit mask does not imply that such access will be allowed to the 3617 file system object in the future, as access rights can be revoked 3618 by the server at any time. 3620 The following access permissions may be requested: 3622 ACCESS_READ: bit 1 Read data from file or read 3623 a directory. 3624 ACCESS_LOOKUP: bit 2 Look up a name in a 3625 directory (no meaning for 3626 non-directory objects). 3627 ACCESS_MODIFY: bit 3 Rewrite existing file data or modify 3628 existing directory entries. 3629 ACCESS_EXTEND: bit 4 Write new data or add 3630 directory entries. 3631 ACCESS_DELETE: bit 5 Delete an existing 3632 directory entry. 3633 ACCESS_EXECUTE: bit 6 Execute file (no meaning 3634 for a directory). 3636 IMPLEMENTATION 3638 In general, it is not sufficient for the client to attempt to 3639 deduce access permissions by inspecting the uid, gid, and mode 3640 fields in the file attributes, since the server may perform uid or 3641 gid mapping or enforce additional access control restrictions. It 3642 is also possible that the NFS version 4 protocol server may not be 3643 in the same ID space as the NFS version 4 protocol client. In these 3644 cases (and perhaps others), the NFS version 4 protocol client can 3645 not reliably perform an access check with only current file 3646 attributes. 3648 In the NFS version 2 protocol, the only reliable way to determine 3649 whether an operation was allowed was to try it and see if it 3650 succeeded or failed. Using the ACCESS procedure in the NFS version 3651 4 protocol, the client can ask the server to indicate whether or 3653 Draft Protocol Specification NFS version 4 October 1999 3655 not one or more classes of operations are permitted. The ACCESS 3656 operation is provided to allow clients to check before doing a 3657 series of operations. This is useful in operating systems (such as 3658 UNIX) where permission checking is done only when a directory is 3659 opened. This procedure is also invoked by NFS client access 3660 procedure (called possibly through access(2)). The intent is to 3661 make the behavior of opening a remote file more consistent with the 3662 behavior of opening a local file. 3664 For NFS version 4, the use of the ACCESS procedure when opening a 3665 regular file is deprecated in favor of using OPEN. 3667 The information returned by the server in response to an ACCESS 3668 call is not permanent. It was correct at the exact time that the 3669 server performed the checks, but not necessarily afterwards. The 3670 server can revoke access permission at any time. 3672 The NFS version 4 protocol client should use the effective 3673 credentials of the user to build the authentication information in 3674 the ACCESS request used to determine access rights. It is the 3675 effective user and group credentials that are used in subsequent 3676 read and write operations. 3678 Many implementations do not directly support the ACCESS_DELETE 3679 permission. Operating systems like UNIX will ignore the 3680 ACCESS_DELETE bit if set on an access request on a non-directory 3681 object. In these systems, delete permission on a file is determined 3682 by the access permissions on the directory in which the file 3683 resides, instead of being determined by the permissions of the file 3684 itself. Therefore the mask returned enumerating which access 3685 rights can be determined will have the ACCESS_DELETE value set to 3686 0. This indicates to the client that the server was unable to 3687 check that particular access right. The ACCESS_DELETE bit in the 3688 access mask returned will then be ignored by the client. 3690 ERRORS 3692 NFS4ERR_IO 3694 NFS4ERR_ACCES 3696 NFS4ERR_SERVERFAULT 3698 NFS4ERR_STALE 3700 NFS4ERR_BADHANDLE 3702 Draft Protocol Specification NFS version 4 October 1999 3704 NFS4ERR_FHEXPIRED 3706 NFS4ERR_WRONGSEC 3708 NFS4ERR_MOVED 3710 Draft Protocol Specification NFS version 4 October 1999 3712 12.2.2. Operation 3: CLOSE - Close File 3714 SYNOPSIS 3716 (cfh), stateid -> stateid 3718 ARGUMENT 3720 struct CLOSE4args { 3721 stateid4 stateid; 3722 }; 3724 RESULT 3726 union CLOSE4res switch (nfsstat4 status) { 3727 case NFS4_OK: 3728 stateid4 stateid; 3729 default: 3730 void; 3731 }; 3733 DESCRIPTION 3735 The CLOSE procedure notifies the server that all share reservations 3736 corresponding to the client supplied stateid should be released. 3738 IMPLEMENTATION 3740 Share reservations for the matching stateid will be released on 3741 successful completion of the CLOSE procedure. 3743 ERRORS 3745 NFS4ERR_INVAL 3747 NFS4ERR_STALE 3749 NFS4ERR_BADHANDLE 3751 Draft Protocol Specification NFS version 4 October 1999 3753 NFS4ERR_SERVERFAULT 3755 NFS4ERR_EXPIRED 3757 NFS4ERR_GRACE 3759 NFS4ERR_FHEXPIRED 3761 NFS4ERR_MOVED 3763 Draft Protocol Specification NFS version 4 October 1999 3765 12.2.3. Operation 4: COMMIT - Commit Cached Data 3767 SYNOPSIS 3769 (cfh), offset, count -> verifier 3771 ARGUMENT 3773 struct COMMIT4args { 3774 /* CURRENT_FH: file */ 3775 offset4 offset; 3776 count4 count; 3777 }; 3779 RESULT 3781 struct COMMIT4resok { 3782 writeverf4 verf; 3783 }; 3785 union COMMIT4res switch (nfsstat4 status) { 3786 case NFS4_OK: 3787 COMMIT4resok resok4; 3788 default: 3789 void; 3790 }; 3792 DESCRIPTION 3794 The COMMIT procedure forces or flushes data to stable storage that 3795 was previously written with a WRITE operation which had the stable 3796 field set to UNSTABLE4. 3798 The offset provided by the client represents the position within 3799 the file at which the flush is to begin. An offset value of 0 3800 (zero) means to flush data starting at the beginning of the file. 3801 The count as provided by the client is the number of bytes of data 3802 to flush. If count is 0 (zero), a flush from offset to the end of 3803 file is done. 3805 The server returns a write verifier upon successful completion of 3806 the COMMIT. The write verifier is used by the client to determine 3807 if the server has restarted or rebooted between the initial 3809 Draft Protocol Specification NFS version 4 October 1999 3811 WRITE(s) and the COMMIT. The client does this by comparing the 3812 write verifier returned from the initial writes and the verifier 3813 returned by the COMMIT procedure. The server must vary the value 3814 of the write verifier at each server event that may lead to a loss 3815 of uncommitted data. Most commonly this occurs when the server is 3816 rebooted; however, other events at the server may result in 3817 uncommitted data loss as well. 3819 IMPLEMENTATION 3821 The COMMIT procedure is similar in operation and semantics to the 3822 POSIX fsync(2) system call that synchronizes a file's state with 3823 the disk (file data and metadata is flushed to disk or stable 3824 storage). COMMIT performs the same operation for a client, flushing 3825 any unsynchronized data and metadata on the server to the server's 3826 disk or stable storage for the specified file. Like fsync(2), it 3827 may be that there is some modified data or no modified data to 3828 synchronize. The data may have been synchronized by the server's 3829 normal periodic buffer synchronization activity. COMMIT should 3830 return NFS4_OK, unless there has been an unexpected error. 3832 COMMIT differs from fsync(2) in that it is possible for the client 3833 to flush a range of the file (most likely triggered by a buffer- 3834 reclamation scheme on the client before file has been completely 3835 written). 3837 The server implementation of COMMIT is reasonably simple. If the 3838 server receives a full file COMMIT request, that is starting at 3839 offset 0 and count 0, it should do the equivalent of fsync()'ing 3840 the file. Otherwise, it should arrange to have the cached data in 3841 the range specified by offset and count to be flushed to stable 3842 storage. In both cases, any metadata associated with the file must 3843 be flushed to stable storage before returning. It is not an error 3844 for there to be nothing to flush on the server. This means that 3845 the data and metadata that needed to be flushed have already been 3846 flushed or lost during the last server failure. 3848 The client implementation of COMMIT is a little more complex. 3849 There are two reasons for wanting to commit a client buffer to 3850 stable storage. The first is that the client wants to reuse a 3851 buffer. In this case, the offset and count of the buffer are sent 3852 to the server in the COMMIT request. The server then flushes any 3853 cached data based on the offset and count, and flushes any metadata 3854 associated with the file. It then returns the status of the flush 3855 and the write verifier. The other reason for the client to 3856 generate a COMMIT is for a full file flush, such as may be done at 3858 Draft Protocol Specification NFS version 4 October 1999 3860 close. In this case, the client would gather all of the buffers 3861 for this file that contain uncommitted data, do the COMMIT 3862 operation with an offset of 0 and count of 0, and then free all of 3863 those buffers. Any other dirty buffers would be sent to the server 3864 in the normal fashion. 3866 After a buffer is written by the client with stable parameter set 3867 to UNSTABLE, the buffer must be considered as modified by the 3868 client until the buffer has either been flushed via a COMMIT 3869 operation or written via a WRITE operation with stable parameter 3870 set to FILE_SYNC or DATA_SYNC. This is done to prevent the buffer 3871 from being freed and reused before the data can be flushed to 3872 stable storage on the server. 3874 When a response comes back from either a WRITE or a COMMIT 3875 operation and it contains a write verifier that is different than 3876 previously returned by the server, the client will need to 3877 retransmit all of the buffers containing uncommitted cached data to 3878 the server. How this is to be done is up to the implementor. If 3879 there is only one buffer of interest, then it should probably be 3880 sent back over in a WRITE request with the appropriate stable 3881 parameter. If there is more than one buffer, it might be worthwhile 3882 retransmitting all of the buffers in WRITE requests with the stable 3883 parameter set to UNSTABLE and then retransmitting the COMMIT 3884 operation to flush all of the data on the server to stable storage. 3885 The timing of these retransmissions is left to the implementor. 3887 The above description applies to page-cache-based systems as well 3888 as buffer-cache-based systems. In those systems, the virtual memory 3889 system will need to be modified instead of the buffer cache. 3891 ERRORS 3893 NFS4ERR_IO 3895 NFS4ERR_LOCKED 3897 NFS4ERR_SERVERFAULT 3899 NFS4ERR_MOVED 3901 Draft Protocol Specification NFS version 4 October 1999 3903 12.2.4. Operation 5: CREATE - Create a Non-Regular File Object 3905 SYNOPSIS 3907 (cfh), name, type, how -> (cfh), change_info 3909 ARGUMENT 3911 struct CREATE4args { 3912 /* CURRENT_FH: directory for creation */ 3913 component4 objname; 3914 fattr4_type type; 3915 createhow4 createhow; 3916 }; 3918 RESULT 3920 struct change_info4 { 3921 bool atomic; 3922 fattr4_change before; 3923 fattr4_change after; 3924 }; 3926 struct CREATE4resok { 3927 change_info4 cinfo; 3928 }; 3930 union CREATE4res switch (nfsstat4 status) { 3931 case NFS4_OK: 3932 CREATE4resok resok4; 3933 default: 3934 void; 3935 }; 3937 DESCRIPTION 3939 The CREATE procedure creates an non-regular file object in a 3940 directory with a given name. The OPEN procedure MUST be used to 3941 create a regular file. 3943 The need for exclusive create semantics for non-regular 3945 Draft Protocol Specification NFS version 4 October 1999 3947 files needs to be decided upon and decisions about storage 3948 location of the verifier will need to be determined as 3949 well. 3951 The objtype determines the type of object to be created: directory, 3952 symlink, etc. The how union may have a value of UNCHECKED, GUARDED, 3953 and EXCLUSIVE. UNCHECKED means that the object should be created 3954 without checking for the existence of a duplicate object in the same 3955 directory. In this case, attrbits and attrvals describe the initial 3956 attributes for the file object. GUARDED specifies that the server 3957 should check for the presence of a duplicate object before performing 3958 the create and should fail the request with NFS4ERR_EXIST if a 3959 duplicate object exists. If the object does not exist, the request is 3960 performed as described for UNCHECKED. EXCLUSIVE specifies that the 3961 server is to follow exclusive creation semantics, using the verifier 3962 to ensure exclusive creation of the target. No attributes may be 3963 provided in this case, since the server may use the target object 3964 meta-data to store the verifier. 3966 For the directory where the new file object was created, the server 3967 returns change_info4 information in cinfo. With the atomic field of 3968 the change_info4 struct, the server will indicate if the before and 3969 after change attributes were obtained atomically with respect to the 3970 file object creation. 3972 The current filehandle is replaced by that of the new object. 3974 IMPLEMENTATION 3976 The CREATE procedure carries support for EXCLUSIVE create forward 3977 from NFS version 3. As in NFS version 3, this mechanism provides 3978 reliable exclusive creation. Exclusive create is invoked when the 3979 how parameter is EXCLUSIVE. In this case, the client provides a 3980 verifier that can reasonably be expected to be unique. A 3981 combination of a client identifier, perhaps the client network 3982 address, and a unique number generated by the client, perhaps the 3983 RPC transaction identifier, may be appropriate. 3985 If the object does not exist, the server creates the object and 3986 stores the verifier in stable storage. For file systems that do not 3987 provide a mechanism for the storage of arbitrary file attributes, 3988 the server may use one or more elements of the object meta-data to 3989 store the verifier. The verifier must be stored in stable storage 3990 to prevent erroneous failure on retransmission of the request. It 3991 is assumed that an exclusive create is being performed because 3992 exclusive semantics are critical to the application. Because of the 3994 Draft Protocol Specification NFS version 4 October 1999 3996 expected usage, exclusive CREATE does not rely solely on the 3997 normally volatile duplicate request cache for storage of the 3998 verifier. The duplicate request cache in volatile storage does not 3999 survive a crash and may actually flush on a long network partition, 4000 opening failure windows. In the UNIX local file system 4001 environment, the expected storage location for the verifier on 4002 creation is the meta-data (time stamps) of the object. For this 4003 reason, an exclusive object create may not include initial 4004 attributes because the server would have nowhere to store the 4005 verifier. 4007 If the server can not support these exclusive create semantics, 4008 possibly because of the requirement to commit the verifier to 4009 stable storage, it should fail the CREATE request with the error, 4010 NFS4ERR_NOTSUPP. 4012 During an exclusive CREATE request, if the object already exists, 4013 the server reconstructs the object's verifier and compares it with 4014 the verifier in the request. If they match, the server treats the 4015 request as a success. The request is presumed to be a duplicate of 4016 an earlier, successful request for which the reply was lost and 4017 that the server duplicate request cache mechanism did not detect. 4018 If the verifiers do not match, the request is rejected with the 4019 status, NFS4ERR_EXIST. 4021 Once the client has performed a successful exclusive create, it 4022 must issue a SETATTR to set the correct object attributes. Until 4023 it does so, it should not rely upon any of the object attributes, 4024 since the server implementation may need to overload object meta- 4025 data to store the verifier. 4027 Use of the GUARDED attribute does not provide exactly-once 4028 semantics. In particular, if a reply is lost and the server does 4029 not detect the retransmission of the request, the procedure can 4030 fail with NFS4ERR_EXIST, even though the create was performed 4031 successfully. 4033 Note: 4035 1. Need to determine an initial set of attributes 4036 that must be set, and a set of attributes that 4037 can optionally be set, on a per-filetype basis. 4038 For instance, if the filetype is a NF4BLK then 4039 the device attributes must be set. 4041 2. Need to consider the symbolic link path as 4042 an "attribute". No need for a READLINK op 4044 Draft Protocol Specification NFS version 4 October 1999 4046 if this is so. Similarly, a filehandle could 4047 be defined as an attribute for LINK. 4049 ERRORS 4051 NFS4ERR_IO 4053 NFS4ERR_ACCES 4055 NFS4ERR_EXIST 4057 NFS4ERR_NOTDIR 4059 NFS4ERR_INVAL 4061 NFS4ERR_NOSPC 4063 NFS4ERR_ROFS 4065 NFS4ERR_NAMETOOLONG 4067 NFS4ERR_DQUOT 4069 NFS4ERR_NOTSUPP 4071 NFS4ERR_SERVERFAULT 4073 NFS4ERR_FHEXPIRED 4075 NFS4ERR_WRONGSEC 4077 NFS4ERR_MOVED 4079 Draft Protocol Specification NFS version 4 October 1999 4081 12.2.5. Operation 6: DELEGPURGE - Purge Delegations Awaiting Recovery 4083 SYNOPSIS 4085 clientid -> 4087 ARGUMENT 4089 struct DELEGPURGE4args { 4090 clientid4 clientid; 4091 }; 4093 RESULT 4095 struct DELEGPURGE4res { 4096 nfsstat4 status; 4097 }; 4099 DESCRIPTION 4101 Purges all of the delegations awaiting recovery for a given client. 4102 This is useful for clients which do not commit delegation 4103 information to stable storage to indicate that conflicting requests 4104 need not be held up awaiting recovery of delegation information. 4106 This operation should also be used by clients which do have 4107 delegation information on stable storage after doing all of 4108 delegation recovery that is needed. Using DELEGPURGE will prevent 4109 any delegations which were made by the server but were not sent to 4110 the client and committed to stable storage from holding up other 4111 clients making conflicting requests. 4113 ERRORS 4115 4117 Draft Protocol Specification NFS version 4 October 1999 4119 12.2.6. Operation 7: DELEGRETURN - Return Delegation 4121 SYNOPSIS 4123 stateid -> 4125 ARGUMENT 4127 struct DELEGRETURN4args { 4128 stateid4 stateid; 4129 }; 4131 RESULT 4133 struct DELEGRETURN4res { 4134 nfsstat4 status; 4135 }; 4137 DESCRIPTION 4139 Returns the delegation represented by the given stateid 4141 ERRORS 4143 4145 Draft Protocol Specification NFS version 4 October 1999 4147 12.2.7. Operation 8: GETATTR - Get Attributes 4149 SYNOPSIS 4151 (cfh), attrbits -> attrbits, attrvals 4153 ARGUMENT 4155 struct GETATTR4args { 4156 /* CURRENT_FH: directory or file */ 4157 bitmap4 attr_request; 4158 }; 4160 RESULT 4162 struct GETATTR4resok { 4163 fattr4 obj_attributes; 4164 }; 4166 union GETATTR4res switch (nfsstat4 status) { 4167 case NFS4_OK: 4168 GETATTR4resok resok4; 4169 default: 4170 void; 4171 }; 4173 DESCRIPTION 4175 The GETATTR procedure will obtain attributes from the server. The 4176 client sets a bit in the bitmap argument for each attribute value 4177 that it would like the server to return. The server returns an 4178 attribute bitmap that indicates the attribute values for which it 4179 was able to return, followed by the attribute values ordered lowest 4180 attribute number first. 4182 The server must return a value for each attribute that the client 4183 requests if the attribute is supported by the server. If the 4184 server does not support an attribute or cannot approximate a useful 4185 value then it must not return the attribute value and must not set 4186 the attribute bit in the result bitmap. The server must return an 4187 error if it supports an attribute but cannot obtain its value. In 4188 that case no attribute values will be returned. 4190 Draft Protocol Specification NFS version 4 October 1999 4192 All servers must support attribute 0 (zero) which is a bitmap of 4193 all supported attributes for the filesystem object. 4195 IMPLEMENTATION 4197 ERRORS 4199 NFS4ERR_IO 4201 NFS4ERR_ACCES 4203 NFS4ERR_INVAL 4205 NFS4ERR_STALE 4207 NFS4ERR_BADHANDLE 4209 NFS4ERR_SERVERFAULT 4211 NFS4ERR_JUKEBOX 4213 NFS4ERR_FHEXPIRED 4215 NFS4ERR_MOVED 4217 Draft Protocol Specification NFS version 4 October 1999 4219 12.2.8. Operation 9: GETFH - Get Current Filehandle 4221 SYNOPSIS 4223 (cfh) -> filehandle 4225 ARGUMENT 4227 /* CURRENT_FH: */ 4228 void; 4230 RESULT 4232 struct GETFH4resok { 4233 nfs4_fh object; 4234 }; 4236 union GETFH4res switch (nfsstat4 status) { 4237 case NFS4_OK: 4238 GETFH4resok resok4; 4239 default: 4240 void; 4241 }; 4243 DESCRIPTION 4245 Returns the current filehandle. Operations that change the current 4246 filehandle like LOOKUP or CREATE to not automatically return the 4247 new filehandle as a result. For instance, if a client needs to 4248 lookup a directory entry and obtain its filehandle then the 4249 following request is needed. 4251 1: PUTFH (directory filehandle) 4252 2: LOOKUP (entry name) 4253 3: GETFH 4255 IMPLEMENTATION 4257 Draft Protocol Specification NFS version 4 October 1999 4259 ERRORS 4261 NFS4ERR_BADHANDLE 4263 NFS4ERR_FHEXPIRED 4265 NFS4ERR_MOVED 4267 NFS4ERR_NOFILEHANDLE 4269 NFS4ERR_SERVERFAULT 4271 NFS4ERR_STALE 4273 NFS4ERR_WRONGSEC 4275 Draft Protocol Specification NFS version 4 October 1999 4277 12.2.9. Operation 10: LINK - Create Link to a File 4279 SYNOPSIS 4281 (cfh), directory, newname -> (cfh), change_info 4283 ARGUMENT 4285 struct LINK4args { 4286 /* CURRENT_FH: file */ 4287 nfs4_fh dir; 4288 component4 newname; 4289 }; 4291 RESULT 4293 struct LINK4resok { 4294 change_info4 cinfo; 4295 }; 4297 union LINK4res switch (nfsstat4 status) { 4298 case NFS4_OK: 4299 LINK4resok resok4; 4300 default: 4301 void; 4302 }; 4304 DESCRIPTION 4306 The LINK procedure creates an additional newname for the file with 4307 the current filehandle in the directory dir. The current file 4308 handle and the directory must reside within the same file system on 4309 the server. 4311 For the directory, the server returns change_info4 information in 4312 cinfo. With the atomic field of the change_info4 struct, the 4313 server will indicate if the before and after change attributes were 4314 obtained atomically with respect to the link creation. 4316 IMPLEMENTATION 4318 Draft Protocol Specification NFS version 4 October 1999 4320 Changes to any property of the hard-linked files are reflected in 4321 all of the linked files. When a hard link is made to a file, the 4322 attributes for the file should have a value for nlink that is one 4323 greater than the value before the LINK. 4325 The comments under RENAME regarding object and target residing on 4326 the same file system apply here as well. The comments regarding the 4327 target name applies as well. 4329 ERRORS 4331 NFS4ERR_IO 4333 NFS4ERR_ACCES 4335 NFS4ERR_EXIST 4337 NFS4ERR_XDEV 4339 NFS4ERR_NOTDIR 4341 NFS4ERR_INVAL 4343 NFS4ERR_NOSPC 4345 NFS4ERR_ROFS 4347 NFS4ERR_MLINK 4349 NFS4ERR_NAMETOOLONG 4351 NFS4ERR_DQUOT 4353 NFS4ERR_STALE 4355 NFS4ERR_BADHANDLE 4357 NFS4ERR_NOTSUPP 4359 NFS4ERR_SERVERFAULT 4361 NFS4ERR_FHEXPIRED 4363 NFS4ERR_MOVED 4365 Draft Protocol Specification NFS version 4 October 1999 4367 12.2.10. Operation 11: LOCK - Create Lock 4369 SYNOPSIS 4371 (cfh) type, seqid, reclaim, owner, offset, length -> stateid, 4372 access 4374 ARGUMENT 4376 enum nfs4_lock_type { 4377 READ_LT = 1, 4378 WRITE_LT = 2, 4379 READW_LT = 3, /* blocking read */ 4380 WRITEW_LT = 4 /* blocking write */ 4381 }; 4383 struct LOCK4args { 4384 /* CURRENT_FH: file */ 4385 nfs4_lock_type type; 4386 seqid4 seqid; 4387 bool reclaim; 4388 stateid4 stateid; 4389 offset4 offset; 4390 length4 length; 4391 }; 4393 RESULT 4395 struct lockres { 4396 stateid4 stateid; 4397 int32_t access; 4398 }; 4400 union LOCK4res switch (nfsstat4 status) { 4401 case NFS4_OK: 4402 lockres result; 4403 default: 4404 void; 4405 }; 4407 DESCRIPTION 4409 Draft Protocol Specification NFS version 4 October 1999 4411 The LOCK procedure requests a record lock for the byte range 4412 specified by the offset and length parameters. The lock type is 4413 also specified to be one of the nfs4_lock_types. If this is a 4414 reclaim request, the reclaim parameter will be TRUE; 4416 IMPLEMENTATION 4418 The File Locking section contains a full description of this and 4419 the other file locking procedures. 4421 ERRORS 4423 NFS4ERR_ACCES 4425 NFS4ERR_ISDIR 4427 NFS4ERR_INVAL 4429 NFS4ERR_STALE 4431 NFS4ERR_BADHANDLE 4433 NFS4ERR_SERVERFAULT 4435 NFS4ERR_GRACE 4437 NFS4ERR_FHEXPIRED 4439 NFS4ERR_MOVED 4441 Draft Protocol Specification NFS version 4 October 1999 4443 12.2.11. Operation 12: LOCKT - Test For Lock 4445 SYNOPSIS 4447 (cfh) type, seqid, reclaim, owner, offset, length -> {void, 4448 NFS4ERR_DENIED -> owner} 4450 ARGUMENT 4452 struct LOCK4args { 4453 /* CURRENT_FH: file */ 4454 nfs4_lock_type type; 4455 seqid4 seqid; 4456 bool reclaim; 4457 nfs_lockowner owner; 4458 offset4 offset; 4459 length4 length; 4460 }; 4462 RESULT 4464 union LOCKT4res switch (nfsstat4 status) { 4465 case NFS4ERR_DENIED: 4466 nfs_lockowner owner; 4467 case NFS4_OK: 4468 void; 4469 default: 4470 void; 4471 }; 4473 DESCRIPTION 4475 The LOCKT procedure tests the lock as specified in the argument. 4476 The owner of the lock is returned in the event it is currently 4477 being held; if no lock is held, nothing other than NFS4_OK is 4478 returned. 4480 IMPLEMENTATION 4482 The File Locking section contains a full description of this and 4483 the other file locking procedures. 4485 Draft Protocol Specification NFS version 4 October 1999 4487 ERRORS 4489 NFS4ERR_ACCES 4491 NFS4ERR_ISDIR 4493 NFS4ERR_INVAL 4495 NFS4ERR_STALE 4497 NFS4ERR_BADHANDLE 4499 NFS4ERR_SERVERFAULT 4501 NFS4ERR_DENIED 4503 NFS4ERR_GRACE 4505 NFS4ERR_FHEXPIRED 4507 NFS4ERR_MOVED 4509 Draft Protocol Specification NFS version 4 October 1999 4511 12.2.12. Operation 13: LOCKU - Unlock File 4513 SYNOPSIS 4515 (cfh) type, seqid, reclaim, owner, offset, length -> stateid 4517 ARGUMENT 4519 struct LOCK4args { 4520 /* CURRENT_FH: file */ 4521 nfs4_lock_type type; 4522 seqid4 seqid; 4523 bool reclaim; 4524 nfs_lockowner owner; 4525 offset4 offset; 4526 length4 length; 4527 }; 4529 RESULT 4531 union LOCKU4res switch (nfsstat4 status) { 4532 case NFS4_OK: 4533 stateid4 stateid_ok; 4534 default: 4535 stateid4 stateid_oth; 4536 }; 4538 DESCRIPTION 4540 The LOCKU procedure unlocks the record lock specified by the 4541 parameters. 4543 IMPLEMENTATION 4545 The File Locking section contains a full description of this and 4546 the other file locking procedures. 4548 ERRORS 4550 NFS4ERR_ACCES 4552 Draft Protocol Specification NFS version 4 October 1999 4554 NFS4ERR_ISDIR 4556 NFS4ERR_INVAL 4558 NFS4ERR_STALE 4560 NFS4ERR_BADHANDLE 4562 NFS4ERR_SERVERFAULT 4564 NFS4ERR_GRACE 4566 NFS4ERR_FHEXPIRED 4568 NFS4ERR_MOVED 4570 Draft Protocol Specification NFS version 4 October 1999 4572 12.2.13. Operation 14: LOOKUP - Lookup Filename 4574 SYNOPSIS 4576 (cfh), filenames -> (cfh) 4578 ARGUMENT 4580 struct LOOKUP4args { 4581 /* CURRENT_FH: directory */ 4582 pathname4 path; 4583 }; 4585 RESULT 4587 struct LOOKUP4res { 4588 /* CURRENT_FH: object */ 4589 nfsstat4 status; 4590 }; 4592 DESCRIPTION 4594 The current filehandle is assumed to refer to a directory. LOOKUP 4595 evaluates the pathname contained in the array of names and obtains 4596 a new current filehandle from the final name. All but the final 4597 name in the list must be the names of directories. 4599 If the pathname cannot be evaluated either because a component 4600 doesn't exist or because the client doesn't have permission to 4601 evaluate a component of the path, then an error will be returned 4602 and the current filehandle will be unchanged. 4604 IMPLEMENTATION 4606 If the client prefers a partial evaluation of the path then a 4607 sequence of LOOKUP operations can be substituted e.g. 4609 1. PUTFH (directory filehandle) 4610 2. LOOKUP "pub" "foo" "bar" 4611 3. GETFH 4613 Draft Protocol Specification NFS version 4 October 1999 4615 or 4617 1. PUTFH (directory filehandle) 4618 2. LOOKUP "pub" 4619 3. GETFH 4620 4. LOOKUP "foo" 4621 5. GETFH 4622 6. LOOKUP "bar" 4623 7. GETFH 4625 NFS version 4 servers depart from the semantics of previous NFS 4626 versions in allowing LOOKUP requests to cross mountpoints on the 4627 server. The client can detect a mountpoint crossing by comparing 4628 the fsid attribute of the directory with the fsid attribute of the 4629 directory looked up. If the fsids are different then the new 4630 directory is a server mountpoint. Unix clients that detect a 4631 mountpoint crossing will need to mount the server's filesystem. 4633 Servers that limit NFS access to "shares" or "exported" filesystems 4634 should provide a pseudo-filesystem into which the exported 4635 filesystems can be integrated, so that clients can browse the 4636 server's namespace. The clients view of a pseudo filesystem will 4637 be limited to paths that lead to exported filesystems. 4639 Note: previous versions of the protocol assigned special semantics 4640 to the names "." and "..". NFS version 4 assigns no special 4641 semantics to these names. The LOOKUPP operator must be used to 4642 lookup a parent directory. 4644 Note that this procedure does not follow symbolic links. The 4645 client is responsible for all parsing of filenames including 4646 filenames that are modified by symbolic links encountered during 4647 the lookup process. 4649 ERRORS 4651 NFS4ERR_NOENT 4653 NFS4ERR_IO 4655 NFS4ERR_ACCES 4657 NFS4ERR_NOTDIR 4659 NFS4ERR_INVAL 4661 NFS4ERR_NAMETOOLONG 4663 Draft Protocol Specification NFS version 4 October 1999 4665 NFS4ERR_STALE 4667 NFS4ERR_SERVERFAULT 4669 NFS4ERR_FHEXPIRED 4671 NFS4ERR_MOVED 4673 Draft Protocol Specification NFS version 4 October 1999 4675 12.2.14. Operation 15: LOOKUPP - Lookup Parent Directory 4677 SYNOPSIS 4679 (cfh) -> (cfh) 4681 ARGUMENT 4683 /* CURRENT_FH: object */ 4684 void; 4686 RESULT 4688 struct LOOKUPP4res { 4689 /* CURRENT_FH: directory */ 4690 nfsstat4 status; 4691 }; 4693 DESCRIPTION 4695 The current filehandle is assumed to refer to a directory. LOOKUPP 4696 assigns the filehandle for its parent directory to be the current 4697 filehandle. If there is no parent directory an ENOENT error must 4698 be returned. Therefore, ENOENT will be returned by the server when 4699 the current filehandle is at the root or top of the server's file 4700 tree. 4702 IMPLEMENTATION 4704 As for LOOKUP, LOOKUPP will also cross mountpoints. 4706 ERRORS 4708 NFS4ERR_NOENT 4710 NFS4ERR_IO 4712 NFS4ERR_ACCES 4714 NFS4ERR_INVAL 4716 Draft Protocol Specification NFS version 4 October 1999 4718 NFS4ERR_STALE 4720 NFS4ERR_SERVERFAULT 4722 NFS4ERR_FHEXPIRED 4724 NFS4ERR_MOVED 4726 Draft Protocol Specification NFS version 4 October 1999 4728 12.2.15. Operation 16: NVERIFY - Verify Difference in Attributes 4730 SYNOPSIS 4732 (cfh), attrbits, attrvals -> - 4734 ARGUMENT 4736 struct NVERIFY4args { 4737 /* CURRENT_FH: object */ 4738 bitmap4 attr_request; 4739 fattr4 obj_attributes; 4740 }; 4742 RESULT 4744 struct NVERIFY4res { 4745 nfsstat4 status; 4746 }; 4748 DESCRIPTION 4750 This operation is used to prefix a sequence of operations to be 4751 performed if one or more attributes have changed on some filesystem 4752 object. If all the attributes match then the error NFS4ERR_SAME 4753 must be returned. 4755 IMPLEMENTATION 4757 This operation is useful as a cache validation operator. If the 4758 object to which the attributes belong has changed then the 4759 following operations may obtain new data associated with that 4760 object. For instance, to check if a file has been changed and 4761 obtain new data if it has: 4763 1. PUTFH (public) 4764 2. LOOKUP "pub" "foo" "bar" 4765 3. NVERIFY attrbits attrs 4766 4. READ 0 32767 4768 Draft Protocol Specification NFS version 4 October 1999 4770 ERRORS 4772 NFS4ERR_IO 4774 NFS4ERR_ACCES 4776 NFS4ERR_STALE 4778 NFS4ERR_BADHANDLE 4780 NFS4ERR_SERVERFAULT 4782 NFS4ERR_FHEXPIRED 4784 NFS4ERR_SAME 4786 NFS4ERR_MOVED 4788 Draft Protocol Specification NFS version 4 October 1999 4790 12.2.16. Operation 17: OPEN - Open a Regular File 4792 SYNOPSIS 4794 (cfh), claim, openhow, owner, seqid, access, deny -> (cfh), 4795 stateid, rflags, access, delegation 4797 ARGUMENT 4799 struct OPEN4args { 4800 open_claim4 claim; 4801 openflag openhow; 4802 nfs_lockowner owner; 4803 seqid4 seqid; 4804 int32_t access; 4805 int32_t deny; 4806 }; 4808 enum createmode4 { 4809 UNCHECKED = 0, 4810 GUARDED = 1, 4811 EXCLUSIVE = 2 4812 }; 4814 union createhow4 switch (createmode4 mode) { 4815 case UNCHECKED: 4816 case GUARDED: 4817 fattr4 createattrs; 4818 case EXCLUSIVE: 4819 createverf4 verf; 4820 }; 4822 enum opentype4 { 4823 OPEN4_NOCREATE 0, 4824 OPEN4_CREATE 1 4825 }; 4827 union openflag switch (opentype4 opentype) { 4828 case OPEN4_CREATE: 4829 createhow4 how; 4830 default: 4831 void; 4832 }; 4834 /* 4835 * Access and Deny constants for open argument 4836 */ 4838 Draft Protocol Specification NFS version 4 October 1999 4840 const OPEN4_ACCESS_READ = 0x0001; 4841 const OPEN4_ACCESS_WRITE= 0x0002; 4842 const OPEN4_ACCESS_BOTH = 0x0003; 4844 const OPEN4_DENY_NONE = 0x0000; 4845 const OPEN4_DENY_READ = 0x0001; 4846 const OPEN4_DENY_WRITE = 0x0002; 4847 const OPEN4_DENY_BOTH = 0x0003; 4849 enum open_delegation_type4 { 4850 OPEN_DELEGATE_NONE = 0, 4851 OPEN_DELEGATE_READ = 1, 4852 OPEN_DELEGATE_WRITE = 2 4853 }; 4855 enum open_claim_type4 { 4856 CLAIM_NULL = 0, 4857 CLAIM_PREVIOUS = 1, 4858 CLAIM_DELEGATE_CUR = 2, 4859 CLAIM_DELEGATE_PREV = 3 4860 }; 4862 struct open_claim_delegate_cur { 4863 pathname4 file; 4864 stateid4 delegate_stateid; 4865 }; 4867 union open_claim4 switch (open_claim_type4 claim) { 4868 /* 4869 * No special rights to file. Ordinary OPEN of the specified file. 4870 */ 4871 case CLAIM_NULL: 4872 /* CURRENT_FH: directory */ 4873 pathname4 file; 4875 /* 4876 * Right to the file established by an open previous to server 4877 * reboot. File identified by filehandle obtained at that time 4878 * rather than by name. 4879 */ 4880 case CLAIM_PREVIOUS: 4881 /* CURRENT_FH: file being reclaimed */ 4882 int32_t delegate_type; 4884 /* 4885 * Right to file based on a delegation granted by the server. 4886 * File is specified by name. 4887 */ 4889 Draft Protocol Specification NFS version 4 October 1999 4891 case CLAIM_DELEGATE_CUR: 4892 /* CURRENT_FH: directory */ 4893 open_claim_delegate_cur delegate_cur_info; 4895 /* Right to file based on a delegation granted to a previous boot 4896 * instance of the client. File is specified by name. 4897 */ 4898 case CLAIM_DELEGATE_PREV: 4899 /* CURRENT_FH: directory */ 4900 pathname4 file_delegate_prev; 4901 }; 4903 RESULT 4905 /* 4906 * Result flags 4907 */ 4908 /* Mandatory locking is in effect for this file. */ 4909 const OPEN4_RESULT_MLOCK = 0x0001; 4911 struct open_read_delegation4 { 4912 stateid4 stateid; /* Stateid for delegation*/ 4913 bool recall; /* Pre-recalled flag for 4914 delegations obtained 4915 by reclaim 4916 (CLAIM_PREVIOUS) */ 4917 nfsace4 permissions; /* Defines users who don't 4918 need an ACCESS call to 4919 open for read */ 4920 }; 4922 struct open_write_delegation4 { 4923 stateid4 stateid; /* Stateid for delegation 4924 be flushed to the server 4925 on close. */ 4926 bool recall; /* Pre-recalled flag for 4927 delegations obtained 4928 by reclaim 4929 (CLAIM_PREVIOUS) */ 4930 nfs_space_limit4 space_limit; /* Defines condition that 4931 the client must check to 4932 determine whether the 4933 file needs to be flushed 4934 to the server on close. 4935 */ 4936 nfsace4 permissions; /* Defines users who don't 4938 Draft Protocol Specification NFS version 4 October 1999 4940 need an ACCESS call as 4941 part of a delegated 4942 open. */ 4943 }; 4945 union open_delegation4 4946 switch (open_delegation_type4 delegation_type) { 4947 case OPEN_DELEGATE_NONE: 4948 void; 4949 case OPEN_DELEGATE_READ: 4950 OPEN4readDelegation read; 4951 case OPEN_DELEGATE_WRITE: 4952 OPEN4writeDelegation write; 4953 }; 4955 struct OPEN4resok { 4956 stateid4 stateid; /* Stateid for open */ 4957 uint32_t rflags; /* Result flags */ 4958 int32_t access; /* Access granted */ 4959 open_delegation4 delegation; /* Info on any open 4960 delegation */ 4961 }; 4963 union OPEN4res switch (nfsstat4 status) { 4964 case NFS4_OK: 4965 /* CURRENT_FH: opened file */ 4966 OPEN4resok result; 4967 default: 4968 void; 4969 }; 4971 DESCRIPTION 4973 The OPEN procedure creates and/or opens a regular file in a 4974 directory with the provided name. If the file does not exist at 4975 the server and creation is desired, specification of the method of 4976 creation is provided by the openhow parameter. The client has the 4977 choice of three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE. 4979 UNCHECKED means that the file should be created without checking 4980 for the existence of a duplicate object in the same directory. For 4981 this type of create, createattrs specifies the initial set of 4982 attributes for the file (NOTE: need to define exactly which 4983 attributes should be set and if the file exists, should the 4984 attributes be modified if the file exists). If GUARDED is 4985 specified, the server checks for the presence of a duplicate object 4987 Draft Protocol Specification NFS version 4 October 1999 4989 by name before performing the create. If a duplicate exists, an 4990 error of NFS4ERR_EXIST is returned as the status. If the object 4991 does not exist, the request is performed as described for 4992 UNCHECKED. 4994 EXCLUSIVE specifies that the server is to follow exclusive creation 4995 semantics, using the verifier to ensure exclusive creation of the 4996 target. The server should check for the presence of a duplicate 4997 object by name. If the object does not exist, the server creates 4998 the object and stores the verifier with the object. If the object 4999 does exist and the stored verifier matches the client provided 5000 verifier, the server uses the existing object as the newly created 5001 object. If the stored verifier does not match, then an error of 5002 NFS4ERR_EXIST is returned. No attributes may be provided in this 5003 case, since the server may use an attribute of the target object to 5004 store the verifier. (NOTE: does a specific attribute need to be 5005 specified for storage of verifier ) 5007 Upon successful creation, the current filehandle is replaced by 5008 that of the new object. 5010 The OPEN procedure provides for DOS SHARE capability with the use 5011 of the access and deny fields of the OPEN arguments. The client 5012 specifies at OPEN the required access and deny modes. For clients 5013 that do not directly support SHAREs (i.e. Unix), the expected deny 5014 value is DENY_NONE. In the case that there is a existing SHARE 5015 reservation that conflicts with the OPEN request, the server 5016 returns the error NFS4ERR_DENIED. For a complete SHARE request, 5017 the client must provide values for the owner and seqid fields for 5018 the OPEN argument. For additional discussion of SHARE semantics 5019 see the section on 'Share Reservations'. 5021 In the case that the client is recovering state from a server 5022 failure, the reclaim field of the OPEN argument is used to signify 5023 that the request is meant to reclaim state previously held. 5025 The "claim" field of the OPEN argument is used to specify the file 5026 to be opened and the state information which the client claims to 5027 possess. There are four basic claim types which cover the various 5028 situations for an OPEN. They are as follows: 5030 CLAIM_NULL 5031 For the client, this is a new OPEN 5032 request and there is no previous state 5033 associate with the file for the client. 5035 Draft Protocol Specification NFS version 4 October 1999 5037 CLAIM_PREVIOUS 5038 The client is claiming basic OPEN state 5039 for a file that was held previous to a 5040 server reboot. Generally used when a 5041 server is returning persistent file 5042 handles; the client may not have the 5043 file name to reclaim the OPEN. 5045 CLAIM_DELEGATE_CUR 5046 The client is claiming a delegation for 5047 OPEN as granted by the server. 5048 Generally this is done as part of 5049 recalling a delegation. 5051 CLAIM_DELEGATE_PREV 5052 The client is claiming a delegation 5053 granted to a previous client instance; 5054 used after the client reboots. 5056 For OPEN requests whose claim type is other than CLAIM_PREVIOUS 5057 (i.e. requests other than those devoted to reclaiming opens after a 5058 server reboot) that reach the server during its grace or lease 5059 expiration period, the server returns an error of NFS4ERR_GRACE. 5061 For any OPEN request, the server may return an open delegation, 5062 which allows further opens and closes to be handled locally on the 5063 client as described in the section Open Delegation. Note that 5064 delegation is up to the server to decide. The client should never 5065 assume that delegation will or will not be granted in a particular 5066 instance. It should always be prepared for either case. A partial 5067 exception is the reclaim (CLAIM_PREVIOUS) case, in which a 5068 delegation type is claimed. In this case, delegation will always 5069 be granted, although the server may specify an immediate recall in 5070 the delegation structure. 5072 IMPLEMENTATION 5074 The OPEN procedure contains support for EXCLUSIVE create. The 5075 mechanism is similar to the support in NFS version 3 [RFC1813]. As 5076 in NFS version 3, this mechanism provides reliable exclusive 5077 creation. Exclusive create is invoked when the how parameter is 5078 EXCLUSIVE. In this case, the client provides a verifier that can 5079 reasonably be expected to be unique. A combination of a client 5080 identifier, perhaps the client network address, and a unique number 5081 generated by the client, perhaps the RPC transaction identifier, 5082 may be appropriate. 5084 If the object does not exist, the server creates the object and 5086 Draft Protocol Specification NFS version 4 October 1999 5088 stores the verifier in stable storage. For file systems that do not 5089 provide a mechanism for the storage of arbitrary file attributes, 5090 the server may use one or more elements of the object meta-data to 5091 store the verifier. The verifier must be stored in stable storage 5092 to prevent erroneous failure on retransmission of the request. It 5093 is assumed that an exclusive create is being performed because 5094 exclusive semantics are critical to the application. Because of the 5095 expected usage, exclusive CREATE does not rely solely on the 5096 normally volatile duplicate request cache for storage of the 5097 verifier. The duplicate request cache in volatile storage does not 5098 survive a crash and may actually flush on a long network partition, 5099 opening failure windows. In the UNIX local file system 5100 environment, the expected storage location for the verifier on 5101 creation is the meta-data (time stamps) of the object. For this 5102 reason, an exclusive object create may not include initial 5103 attributes because the server would have nowhere to store the 5104 verifier. 5106 If the server can not support these exclusive create semantics, 5107 possibly because of the requirement to commit the verifier to 5108 stable storage, it should fail the OPEN request with the error, 5109 NFS4ERR_NOTSUPP. 5111 During an exclusive CREATE request, if the object already exists, 5112 the server reconstructs the object's verifier and compares it with 5113 the verifier in the request. If they match, the server treats the 5114 request as a success. The request is presumed to be a duplicate of 5115 an earlier, successful request for which the reply was lost and 5116 that the server duplicate request cache mechanism did not detect. 5117 If the verifiers do not match, the request is rejected with the 5118 status, NFS4ERR_EXIST. 5120 Once the client has performed a successful exclusive create, it 5121 must issue a SETATTR to set the correct object attributes. Until 5122 it does so, it should not rely upon any of the object attributes, 5123 since the server implementation may need to overload object meta- 5124 data to store the verifier. The subsequent SETATTR must not occur 5125 in the same COMPOUND request as the OPEN. This separation will 5126 guarantee that the exclusive create mechanism will continue to 5127 function properly in the face of retransmission of the request. 5129 Use of the GUARDED attribute does not provide exactly-once 5130 semantics. In particular, if a reply is lost and the server does 5131 not detect the retransmission of the request, the procedure can 5132 fail with NFS4ERR_EXIST, even though the create was performed 5133 successfully. 5135 For SHARE reservations, the client must specify a value for access 5137 Draft Protocol Specification NFS version 4 October 1999 5139 that is one of READ, WRITE, or BOTH. For deny, the client must 5140 specify one of NONE, READ, WRITE, or BOTH. If the client fails to 5141 do this, the server must return NFS4ERR_INVAL. 5143 The OPEN call 5145 ERRORS 5147 NFS4ERR_IO 5149 NFS4ERR_ACCES 5151 NFS4ERR_EXIST 5153 NFS4ERR_NOTDIR 5155 NFS4ERR_NOSPC 5157 NFS4ERR_ROFS 5159 NFS4ERR_NAMETOOLONG 5161 NFS4ERR_DQUOT 5163 NFS4ERR_NOTSUPP 5165 NFS4ERR_SERVERFAULT 5167 NFS4ERR_SHARE_DENIED 5169 NFS4ERR_GRACE 5171 NFS4ERR_MOVED 5173 Draft Protocol Specification NFS version 4 October 1999 5175 12.2.17. Operation 18: OPENATTR - Open Named Attribute Directory 5177 SYNOPSIS 5179 (cfh) -> (cfh) 5181 ARGUMENT 5183 /* CURRENT_FH: file or directory */ 5184 void; 5186 RESULT 5188 struct OPENATTR4res { 5189 /* CURRENT_FH: name attr directory*/ 5190 nfsstat4 status; 5191 }; 5193 DESCRIPTION 5195 The OPENATTR procedure is used to obtain the filehandle of the 5196 named attribute directory associated with the current filehandle. 5197 The result of the OPENATTR will be a filehandle of type NF4ATTRDIR. 5198 From this filehandle, READDIR and LOOKUP procedures can be used to 5199 obtain filehandles for the various named attributes associated with 5200 the original file system object. Filehandles returned within the 5201 named attribute directory will have a type of NF4NAMEDATTR. 5203 IMPLEMENTATION 5205 If the server does not support named attributes for the current 5206 filehandle, an error of NFS4ERR_NOTSUPP will be returned to the 5207 client. 5209 ERRORS 5211 NFS4ERR_NOENT 5213 NFS4ERR_IO 5215 Draft Protocol Specification NFS version 4 October 1999 5217 NFS4ERR_ACCES 5219 NFS4ERR_INVAL 5221 NFS4ERR_STALE 5223 NFS4ERR_BADHANDLE 5225 NFS4ERR_NOTSUPP 5227 NFS4ERR_SERVERFAULT 5229 NFS4ERR_JUKEBOX 5231 NFS4ERR_FHEXPIRED 5233 NFS4ERR_WRONGSEC 5235 NFS4ERR_MOVED 5237 Draft Protocol Specification NFS version 4 October 1999 5239 12.2.18. Operation 19: PUTFH - Set Current Filehandle 5241 SYNOPSIS 5243 filehandle -> (cfh) 5245 ARGUMENT 5247 struct PUTFH4args { 5248 nfs4_fh object; 5249 }; 5251 RESULT 5253 struct PUTFH4res { 5254 /* CURRENT_FH: */ 5255 nfsstat4 status; 5256 }; 5258 DESCRIPTION 5260 Replaces the current filehandle with the filehandle provided as an 5261 argument. 5263 IMPLEMENTATION 5265 Commonly used as the first operator in any NFS request to set the 5266 context for following operations. 5268 ERRORS 5270 NFS4ERR_BADHANDLE 5272 NFS4ERR_FHEXPIRED 5274 NFS4ERR_MOVED 5276 NFS4ERR_SERVERFAULT 5278 Draft Protocol Specification NFS version 4 October 1999 5280 NFS4ERR_STALE 5282 NFS4ERR_WRONGSEC 5284 Draft Protocol Specification NFS version 4 October 1999 5286 12.2.19. Operation 20: PUTPUBFH - Set Public Filehandle 5288 SYNOPSIS 5290 - -> (cfh) 5292 ARGUMENT 5294 void; 5296 RESULT 5298 struct PUTPUBFH4res { 5299 /* CURRENT_FH: root fh */ 5300 nfsstat4 status; 5301 }; 5303 DESCRIPTION 5305 Replaces the current filehandle with the filehandle that represents 5306 the public filehandle of the server's namespace. This filehandle 5307 may be different from the "root" filehandle which may be associated 5308 with some other directory on the server. 5310 IMPLEMENTATION 5312 Used as the first operator in any NFS request to set the context 5313 for following operations. 5315 ERRORS 5317 NFS4ERR_SERVERFAULT NFS4ERR_WRONGSEC 5319 Draft Protocol Specification NFS version 4 October 1999 5321 12.2.20. Operation 21: PUTROOTFH - Set Root Filehandle 5323 SYNOPSIS 5325 - -> (cfh) 5327 ARGUMENT 5329 void; 5331 RESULT 5333 struct PUTROOTFH4res { 5334 /* CURRENT_FH: root fh */ 5335 nfsstat4 status; 5336 }; 5338 DESCRIPTION 5340 Replaces the current filehandle with the filehandle that represents 5341 the root of the server's namespace. From this filehandle a LOOKUP 5342 operation can locate any other filehandle on the server. This 5343 filehandle may be different from the "public" filehandle which may 5344 be associated with some other directory on the server. 5346 IMPLEMENTATION 5348 Commonly used as the first operator in any NFS request to set the 5349 context for following operations. 5351 ERRORS 5353 NFS4ERR_SERVERFAULT 5355 NFS4ERR_WRONTSEC 5357 Draft Protocol Specification NFS version 4 October 1999 5359 12.2.21. Operation 22: READ - Read from File 5361 SYNOPSIS 5363 (cfh), offset, count, stateid -> eof, data 5365 ARGUMENT 5367 struct READ4args { 5368 /* CURRENT_FH: file */ 5369 stateid4 stateid; 5370 offset4 offset; 5371 count4 count; 5372 }; 5374 RESULT 5376 struct READ4resok { 5377 bool eof; 5378 opaque data<>; 5379 }; 5381 union READ4res switch (nfsstat4 status) { 5382 case NFS4_OK: 5383 READ4resok resok4; 5384 default: 5385 void; 5386 }; 5388 DESCRIPTION 5390 The READ procedure reads data from the regular file identified by 5391 the current filehandle. 5393 The client provides an offset of where the READ is to start and a 5394 count of how many bytes are to be read. An offset of 0 (zero) 5395 means to read data starting at the beginning of the file. If offset 5396 is greater than or equal to the size of the file, the status, 5397 NFS4_OK, is returned with a data length set to 0 (zero) and eof set 5398 to TRUE. The READ is subject to access permissions checking. 5400 If the client specifies a count value of 0 (zero), the READ 5402 Draft Protocol Specification NFS version 4 October 1999 5404 succeeds and returns 0 (zero) bytes of data again subject to access 5405 permissions checking. The server may choose to return fewer bytes 5406 than specified by the client. The client needs to check for this 5407 condition and handle the condition appropriately. 5409 The stateid value for a READ request represents a value returned 5410 from a previous record lock or share reservation request. Used by 5411 the server to verify that the associated lock is still valid and to 5412 update lease timeouts for the client. 5414 If the read ended at the end-of-file (formally, in a correctly 5415 formed READ request, if offset + count is equal to the size of the 5416 file), eof is returned as TRUE; otherwise it is FALSE. A successful 5417 READ of an empty file will always return eof as TRUE. 5419 IMPLEMENTATION 5421 It is possible for the server to return fewer than count bytes of 5422 data. If the server returns less than the count requested and eof 5423 set to FALSE, the client should issue another READ to get the 5424 remaining data. A server may return less data than requested under 5425 several circumstances. The file may have been truncated by another 5426 client or perhaps on the server itself, changing the file size from 5427 what the requesting client believes to be the case. This would 5428 reduce the actual amount of data available to the client. It is 5429 possible that the server may back off the transfer size and reduce 5430 the read request return. Server resource exhaustion may also occur 5431 necessitating a smaller read return. 5433 If the file is locked the server will return an NFS4ERR_LOCKED 5434 error. Since the lock may be of short duration, the client may 5435 choose to retransmit the READ request (with exponential backoff) 5436 until the operation succeeds. 5438 ERRORS 5440 NFS4ERR_IO 5442 NFS4ERR_NXIO 5444 NFS4ERR_ACCES 5446 NFS4ERR_INVAL 5448 NFS4ERR_STALE 5450 Draft Protocol Specification NFS version 4 October 1999 5452 NFS4ERR_BADHANDLE 5454 NFS4ERR_SERVERFAULT 5456 NFS4ERR_DENIED 5458 NFS4ERR_JUKEBOX 5460 NFS4ERR_EXPIRED 5462 NFS4ERR_LOCKED 5464 NFS4ERR_GRACE 5466 NFS4ERR_FHEXPIRED 5468 NFS4ERR_WRONGSEC 5470 NFS4ERR_MOVED 5472 Draft Protocol Specification NFS version 4 October 1999 5474 12.2.22. Operation 23: READDIR - Read Directory 5476 SYNOPSIS 5477 (cfh), cookie, dircount, maxcount, attrbits -> { cookie, filename, 5478 attrbits, attributes } 5480 ARGUMENT 5482 struct READDIR4args { 5483 /* CURRENT_FH: directory */ 5484 nfs_cookie4 cookie; 5485 count4 dircount; 5486 count4 maxcount; 5487 bitmap4 attr_request; 5489 }; 5491 RESULT 5493 struct entry4 { 5494 nfs_cookie4 cookie; 5495 component4 name; 5496 fattr4 attrs; 5497 entry4 *nextentry; 5498 }; 5500 struct dirlist4 { 5501 entry4 *entries; 5502 bool eof; 5503 }; 5505 struct READDIR4resok { 5506 dirlist4 reply; 5507 }; 5509 union READDIR4res switch (nfsstat4 status) { 5510 case NFS4_OK: 5511 READDIR4resok resok4; 5512 default: 5513 void; 5514 }; 5516 Draft Protocol Specification NFS version 4 October 1999 5518 DESCRIPTION 5520 The READDIR procedure retrieves a variable number of entries from a 5521 file system directory and returns complete information about each 5522 entry along with information to allow the client to request 5523 additional directory entries in a subsequent READDIR. 5525 The arguments contain a cookie value that represents where the 5526 READDIR should start within the directory. A value of 0 (zero) for 5527 the cookie is used to start reading at the beginning of the 5528 directory. For subsequent READDIR requests, the client specifies a 5529 cookie value that is provided by the server on a previous READDIR 5530 request. 5532 The dircount portion of the argument is the maximum number of bytes 5533 of directory information that should be returned. This value does 5534 not include the size of attributes or filehandle values that may be 5535 returned in the result. 5537 The maxcount value of the argument specifies the maximum number of 5538 bytes for the result. This maximum size represents all of the data 5539 being returned and includes the XDR overhead. The server may 5540 return less data. 5542 Finally, attrbits represents the list of attributes the client 5543 wants returned for each directory entry supplied by the server. 5545 On successful return, the server's response will provide a list of 5546 directory entries. Each of these entries contains the name of the 5547 directory entry, a cookie value for that entry, and the associated 5548 attributes as requested. 5550 The cookie value is only meaningful to the server and is used as a 5551 "bookmark" for the directory entry. As mentioned, this cookie is 5552 used by the client for subsequent READDIR operations so that it may 5553 continue reading a directory. The cookie is similar in concept to 5554 a READ offset but should not be interpreted as such by the client. 5555 Ideally, the cookie value should not change if the directory is 5556 modified. 5558 In some cases, the server may encounter an error while obtaining 5559 the attributes for a directory entry. Instead of returning an 5560 error for the entire READDIR operation, the server can instead 5561 return the attribute 'fattr4_rdattr_error'. This way the server is 5562 able to communicate the failure to the client and not fail the 5563 entire operation in the instance of what might be a transient 5564 failure. Obviously, the client must request the 5565 fattr4_rdattr_error attribute for this method to work properly. If 5567 Draft Protocol Specification NFS version 4 October 1999 5569 the client does not request the attribute, the server has no choice 5570 but to return failure for the entire READDIR operation. 5572 IMPLEMENTATION 5574 Issues that need to be understood for this procedure include 5575 increased cache flushing activity on the client (as new file 5576 handles are returned with names which are entered into caches) and 5577 over-the-wire overhead versus expected subsequent LOOKUP and 5578 GETATTR elimination. 5580 The dircount and maxcount fields are included as an optimization. 5581 Consider a READDIR call on a UNIX operating system implementation 5582 for 1048 bytes; the reply does not contain many entries because of 5583 the overhead due to attributes and file handles. An alternative is 5584 to issue a READDIR call for 8192 bytes and then only use the first 5585 1048 bytes of directory information. However, the server doesn't 5586 know that all that is needed is 1048 bytes of directory information 5587 (as would be returned by READDIR). It sees the 8192 byte request 5588 and issues a VOP_READDIR for 8192 bytes. It then steps through all 5589 of those directory entries, obtaining attributes and file handles 5590 for each entry. When it encodes the result, the server only 5591 encodes until it gets 8192 bytes of results which include the 5592 attributes and file handles. Thus, it has done a larger VOP_READDIR 5593 and many more attribute fetches than it needed to. The ratio of the 5594 directory entry size to the size of the attributes plus the size of 5595 the file handle is usually at least 8 to 1. The server has done 5596 much more work than it needed to. 5598 The solution to this problem is for the client to provide two 5599 counts to the server. The first is the number of bytes of directory 5600 information that the client really wants, dircount. The second is 5601 the maximum number of bytes in the result, including the attributes 5602 and file handles, maxcount. Thus, the server will issue a 5603 VOP_READDIR for only the number of bytes that the client really 5604 wants to get, not an inflated number. This should help to reduce 5605 the size of VOP_READDIR requests on the server, thus reducing the 5606 amount of work done there, and to reduce the number of VOP_LOOKUP, 5607 VOP_GETATTR, and other calls done by the server to construct 5608 attributes and file handles. 5610 ERRORS 5612 NFS4ERR_IO 5614 NFS4ERR_ACCES 5616 Draft Protocol Specification NFS version 4 October 1999 5618 NFS4ERR_NOTDIR 5620 NFS4ERR_INVAL 5622 NFS4ERR_STALE 5624 NFS4ERR_BADHANDLE 5626 NFS4ERR_BAD_COOKIE 5628 NFS4ERR_TOOSMALL 5630 NFS4ERR_NOTSUPP 5632 NFS4ERR_SERVERFAULT 5634 NFS4ERR_JUKEBOX 5636 NFS4ERR_FHEXPIRED 5638 NFS4ERR_WRONGSEC 5640 NFS4ERR_MOVED 5642 Draft Protocol Specification NFS version 4 October 1999 5644 12.2.23. Operation 24: READLINK - Read Symbolic Link 5646 SYNOPSIS 5648 (cfh) -> linktext 5650 ARGUMENT 5652 /* CURRENT_FH: symlink */ 5653 void; 5655 RESULT 5657 struct READLINK4resok { 5658 linktext4 link; 5659 }; 5661 union READLINK4res switch (nfsstat4 status) { 5662 case NFS4_OK: 5663 READLINK4resok resok4; 5664 default: 5665 void; 5666 }; 5668 DESCRIPTION 5670 READLINK reads the data associated with a symbolic link. The data 5671 is a UTF-8 string that is opaque to the server. That is, whether 5672 created by an NFS client or created locally on the server, the data 5673 in a symbolic link is not interpreted when created, but is simply 5674 stored. 5676 IMPLEMENTATION 5678 A symbolic link is nominally a pointer to another file. The data 5679 is not necessarily interpreted by the server, just stored in the 5680 file. It is possible for a client implementation to store a path 5681 name that is not meaningful to the server operating system in a 5682 symbolic link. A READLINK operation returns the data to the client 5683 for interpretation. If different implementations want to share 5684 access to symbolic links, then they must agree on the 5686 Draft Protocol Specification NFS version 4 October 1999 5688 interpretation of the data in the symbolic link. 5690 The READLINK operation is only allowed on objects of type, NF4LNK. 5691 The server should return the error, NFS4ERR_INVAL, if the object is 5692 not of type, NF4LNK. 5694 ERRORS 5696 NFS4ERR_IO 5698 NFS4ERR_INVAL 5700 NFS4ERR_ACCES 5702 NFS4ERR_STALE 5704 NFS4ERR_BADHANDLE 5706 NFS4ERR_NOTSUPP 5708 NFS4ERR_SERVERFAULT 5710 NFS4ERR_JUKEBOX 5712 NFS4ERR_FHEXPIRED 5714 NFS4ERR_WRONGSEC 5716 NFS4ERR_MOVED 5718 Draft Protocol Specification NFS version 4 October 1999 5720 12.2.24. Operation 25: REMOVE - Remove Filesystem Object 5722 SYNOPSIS 5724 (cfh), filename -> change_info 5726 ARGUMENT 5728 struct REMOVE4args { 5729 /* CURRENT_FH: directory */ 5730 component4 target; 5731 }; 5733 RESULT 5735 struct REMOVE4resok { 5736 change_info4 cinfo; 5737 } 5739 union REMOVE4res switch (nfsstat4 status) { 5740 case NFS4_OK: 5741 REMOVE4resok resok4; 5742 default: 5743 void; 5744 } 5746 DESCRIPTION 5748 The REMOVE procecure removes (deletes) a directory entry named by 5749 filename from the directory corresponding to the current 5750 filehandle. If the entry in the directory was the last reference 5751 to the corresponding file system object, the object may be 5752 destroyed. 5754 For the directory where the filename was removed, the server 5755 returns change_info4 information in cinfo. With the atomic field 5756 of the change_info4 struct, the server will indicate if the before 5757 and after change attributes were obtained atomically with respect 5758 to the removal. 5760 Draft Protocol Specification NFS version 4 October 1999 5762 IMPLEMENTATION 5764 NFS versions 2 and 3 required a different operator RMDIR for 5765 directory removal. NFS version 4 REMOVE can be used to delete any 5766 directory entry independent of its filetype. 5768 The concept of last reference is server specific. However, if the 5769 nlink field in the previous attributes of the object had the value 5770 1, the client should not rely on referring to the object via a file 5771 handle. Likewise, the client should not rely on the resources (disk 5772 space, directory entry, and so on.) formerly associated with the 5773 object becoming immediately available. Thus, if a client needs to 5774 be able to continue to access a file after using REMOVE to remove 5775 it, the client should take steps to make sure that the file will 5776 still be accessible. The usual mechanism used is to use RENAME to 5777 rename the file from its old name to a new hidden name. 5779 ERRORS 5781 NFS4ERR_NOENT 5783 NFS4ERR_IO 5785 NFS4ERR_ACCES 5787 NFS4ERR_NOTDIR 5789 NFS4ERR_ROFS 5791 NFS4ERR_NAMETOOLONG 5793 NFS4ERR_NOTEMPTY 5795 NFS4ERR_STALE 5797 NFS4ERR_BADHANDLE 5799 NFS4ERR_NOTSUPP 5801 NFS4ERR_SERVERFAULT 5803 NFS4ERR_FHEXPIRED 5805 NFS4ERR_WRONGSEC 5807 NFS4ERR_MOVED 5809 Draft Protocol Specification NFS version 4 October 1999 5811 12.2.25. Operation 26: RENAME - Rename Directory Entry 5813 SYNOPSIS 5815 (cfh), oldname, newdir, newname -> source_change_info, 5816 target_change_info 5818 ARGUMENT 5820 struct RENAME4args { 5821 /* CURRENT_FH: source directory */ 5822 component4 oldname; 5823 nfs4_fh newdir; 5824 component4 newname; 5825 }; 5827 RESULT 5829 struct RENAME4resok { 5830 change_info4 source_cinfo; 5831 change_info4 target_cinfo; 5832 }; 5834 union RENAME4res switch (nfsstat4 status) { 5835 case NFS4_OK: 5836 RENAME4resok resok4; 5837 default: 5838 void; 5839 }; 5841 DESCRIPTION 5843 RENAME renames the object identified by oldname in the directory 5844 corresponding to the current filehandle to newname in directory 5845 newdir. The operation is required to be atomic to the client. 5846 Source and target directories must reside on the same file system 5847 on the server. 5849 If the directory, newdir, already contains an entry with the name, 5850 newname, the source object must be compatible with the target: 5851 either both are non-directories or both are directories and the 5852 target must be empty. If compatible, the existing target is removed 5854 Draft Protocol Specification NFS version 4 October 1999 5856 before the rename occurs. If they are not compatible or if the 5857 target is a directory but not empty, the server should return the 5858 error, NFS4ERR_EXIST. 5860 If oldname and newname both refer to the same file (they might be 5861 hard links of each other), then RENAME should perform no action and 5862 return success. 5864 For both directories involved in the RENAME, the server returns 5865 change_info4 information. With the atomic field of the 5866 change_info4 struct, the server will indicate if the before and 5867 after change attributes were obtained atomically with respect to 5868 the rename. 5870 IMPLEMENTATION 5872 The RENAME operation must be atomic to the client. The statement 5873 "source and target directories must reside on the same file system 5874 on the server" means that the fsid fields in the attributes for the 5875 directories are the same. If they reside on different file systems, 5876 the error, NFS4ERR_XDEV, is returned. Even though the operation is 5877 atomic, the status, NFS4ERR_MLINK, may be returned if the server 5878 used a "unlink/link/unlink" sequence internally. 5880 A file handle may or may not become stale on a rename. However, 5881 server implementors are strongly encouraged to attempt to keep file 5882 handles from becoming stale in this fashion. 5884 On some servers, the filenames, "." and "..", are illegal as either 5885 oldname or newname. In addition, neither oldname nor newname can be 5886 an alias for the source directory. These servers will return the 5887 error, NFS4ERR_INVAL, in these cases. 5889 ERRORS 5891 NFS4ERR_NOENT 5893 NFS4ERR_IO 5895 NFS4ERR_ACCES 5897 NFS4ERR_EXIST 5899 NFS4ERR_XDEV 5901 Draft Protocol Specification NFS version 4 October 1999 5903 NFS4ERR_NOTDIR 5905 NFS4ERR_ISDIR 5907 NFS4ERR_INVAL 5909 NFS4ERR_NOSPC 5911 NFS4ERR_ROFS 5913 NFS4ERR_MLINK 5915 NFS4ERR_NAMETOOLONG 5917 NFS4ERR_NOTEMPTY 5919 NFS4ERR_DQUOT 5921 NFS4ERR_STALE 5923 NFS4ERR_BADHANDLE 5925 NFS4ERR_NOTSUPP 5927 NFS4ERR_SERVERFAULT 5929 NFS4ERR_FHEXPIRED 5931 NFS4ERR_WRONGSEC 5933 NFS4ERR_MOVED 5935 Draft Protocol Specification NFS version 4 October 1999 5937 12.2.26. Operation 27: RENEW - Renew a Lease 5939 SYNOPSIS 5941 stateid -> () 5943 ARGUMENT 5945 struct RENEW4args { 5946 stateid4 stateid; 5947 }; 5949 RESULT 5951 struct RENEW4res { 5952 nfsstat4 status; 5953 }; 5955 DESCRIPTION 5957 The RENEW procedure is used by the client to renew leases which it 5958 currently holds at a server. The processing the RENEW request, the 5959 server renews all leases associated with the client. The 5960 associated leases are determined by the client id provided via the 5961 SETCLIENTID procedure. 5963 IMPLEMENTATION 5965 ERRORS 5967 NFS4ERR_SERVERFAULT 5969 NFS4ERR_EXPIRED 5971 NFS4ERR_GRACE 5973 NFS4ERR_WRONGSEC 5975 NFS4ERR_MOVED 5977 Draft Protocol Specification NFS version 4 October 1999 5979 12.2.27. Operation 28: RESTOREFH - Restore Saved Filehandle 5981 SYNOPSIS 5983 (sfh) -> (cfh) 5985 ARGUMENT 5987 /* SAVED_FH: */ 5988 void; 5990 RESULT 5992 struct RESTOREFH4res { 5993 /* CURRENT_FH: value of saved fh */ 5994 nfsstat4 status; 5995 }; 5997 DESCRIPTION 5999 Set the current filehandle to the value in the saved filehandle. 6000 If there is no saved filehandle then return an error NFS4ERR_INVAL. 6002 IMPLEMENTATION 6004 Procedures like OPEN and LOOKUP use the current filehandle to 6005 represent a directory and replace it with a new filehandle. 6006 Assuming the previous filehandle was saved with a SAVEFH operator, 6007 the previous filehandle can be restored as the current filehandle. 6008 This is commonly used to obtain post-operation attributes for the 6009 directory, e.g. 6011 1. PUTFH (directory filehandle) 6012 2. SAVEFH 6013 3. GETATTR attrbits (pre-op dir attrs) 6014 4. CREATE optbits "foo" attrs 6015 5. GETATTR attrbits (file attributes) 6016 6. RESTOREFH 6017 7. GETATTR attrbits (post-op dir attrs) 6019 Draft Protocol Specification NFS version 4 October 1999 6021 ERRORS 6023 NFS4ERR_BADHANDLE 6025 NFS4ERR_FHEXPIRED 6027 NFS4ERR_MOVED 6029 NFS4ERR_NOFILEHANDLE 6031 NFS4ERR_SERVERFAULT 6033 NFS4ERR_STALE 6035 NFS4ERR_WRONGSEC 6037 Draft Protocol Specification NFS version 4 October 1999 6039 12.2.28. Operation 29: SAVEFH - Save Current Filehandle 6041 SYNOPSIS 6043 (cfh) -> (sfh) 6045 ARGUMENT 6047 /* CURRENT_FH: */ 6048 void; 6050 RESULT 6052 struct SAVEFH4res { 6053 /* SAVED_FH: value of current fh */ 6054 nfsstat4 status; 6055 }; 6057 DESCRIPTION 6059 Save the current filehandle. If a previous filehandle was saved 6060 then it is no longer accessible. The saved filehandle can be 6061 restored as the current filehandle with the RESTOREFH operator. 6063 IMPLEMENTATION 6065 ERRORS 6067 NFS4ERR_BADHANDLE 6069 NFS4ERR_FHEXPIRED 6071 NFS4ERR_MOVED 6073 NFS4ERR_NOFILEHANDLE 6075 NFS4ERR_SERVERFAULT 6077 NFS4ERR_STALE 6079 Draft Protocol Specification NFS version 4 October 1999 6081 NFS4ERR_WRONGSEC 6083 Draft Protocol Specification NFS version 4 October 1999 6085 12.2.29. Operation 30: SECINFO - Obtain Available Security 6087 SYNOPSIS 6089 (cfh), filename -> { secinfo } 6091 ARGUMENT 6093 struct SECINFO4args { 6094 /* CURRENT_FH: */ 6095 component4 name; 6096 }; 6098 RESULT 6100 struct rpcsec_gss_info { 6101 sec_oid4 oid; 6102 qop4 qop; 6103 rpc_gss_svc_t service; 6104 }; 6106 struct secinfo4 { 6107 unsigned int flavor; 6108 opaque flavor_info<>; /* null for AUTH_SYS, AUTH_NONE; 6109 contains rpcsec_gss_info for 6110 RPCSEC_GSS. */ 6111 }; 6113 struct SECINFO4resok { 6114 secinfo4 reply<>; 6115 }; 6117 union SECINFO4res switch (nfsstat4 status) { 6118 case NFS4_OK: 6119 SECINFO4resok resok4; 6120 default: 6121 void; 6122 }; 6124 DESCRIPTION 6126 Draft Protocol Specification NFS version 4 October 1999 6128 The SECINFO procedure is used by the client to obtain a list of 6129 valid RPC authentication flavors for a specific file handle, file 6130 name pair. The result will contain an array which represents the 6131 security mechanisms available. The array entries are represented 6132 by the secinfo4 structure. The field 'flavor' will contain a value 6133 of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or RPCSEC_GSS (as 6134 defined in [RFC2203]). 6136 For the flavors, AUTH_NONE, and AUTH_SYS no additional security 6137 information is returned. For a return value of RPCSEC_GSS, a 6138 security triple is returned that contains the mechanism object id 6139 (as defined in [RFC2078]), the quality of protection (as defined in 6140 [RFC2078]) and the service type (as defined in [RFC2203]). It is 6141 possible for SECINFO to return multiple entries with flavor equal 6142 to RPCSEC_GSS with different security triple values. 6144 IMPLEMENTATION 6146 The SECINFO procedure is expected to be used by the NFS client when 6147 the error value of NFS4ERR_WRONGSEC is returned from another NFS 6148 procedure. This signifies to the client that the server's security 6149 policy is different from what the client is currently using. At 6150 this point, the client is expected to obtain a list of possible 6151 security flavors and choose what best suits its policies. 6153 ERRORS 6155 NFS4ERR_SERVERFAULT 6157 NFS4ERR_MOVED 6159 Draft Protocol Specification NFS version 4 October 1999 6161 12.2.30. Operation 31: SETATTR - Set Attributes 6163 SYNOPSIS 6165 (cfh), attrbits, attrvals -> - 6167 ARGUMENT 6169 struct SETATTR4args { 6170 /* CURRENT_FH: target object */ 6171 stateid4 stateid; 6172 fattr4 obj_attributes; 6173 }; 6175 RESULT 6177 struct SETATTR4res { 6178 nfsstat4 status; 6179 }; 6181 DESCRIPTION 6183 The SETATTR Procedure changes one or more of the attributes of a 6184 file system object. The new attributes are specified with a bitmap 6185 and the attributes that follow the bitmap in bit order. 6187 The stateid is necessary for SETATTR's that change the size of file 6188 (modify the attribute object_size). This stateid represents a 6189 record lock, share reservation, or delegation which must be valid 6190 for the SETATTR to modify the file data. 6192 IMPLEMENTATION 6194 The file size attribute is used to request changes to the size of a 6195 file. A value of 0 (zero) causes the file to be truncated, a value 6196 less than the current size of the file causes data from new size to 6197 the end of the file to be discarded, and a size greater than the 6198 current size of the file causes logically zeroed data bytes to be 6199 added to the end of the file. Servers are free to implement this 6200 using holes or actual zero data bytes. Clients should not make any 6202 Draft Protocol Specification NFS version 4 October 1999 6204 assumptions regarding a server's implementation of this feature, 6205 beyond that the bytes returned will be zeroed. Servers must support 6206 extending the file size via SETATTR. 6208 SETATTR is not guaranteed atomic. A failed SETATTR may partially 6209 change a file's attributes. 6211 Changing the size of a file with SETATTR indirectly changes the 6212 time_modify. A client must account for this as size changes can 6213 result in data deletion. 6215 If server and client times differ, programs that compare client 6216 time to file times can break. A time maintenance protocol should be 6217 used to limit client/server time skew. 6219 If the server cannot successfully set all the attributes it must 6220 return an NFS4ERR_INVAL error. If the server can only support 32 6221 bit offsets and sizes, a SETATTR request to set the size of a file 6222 to larger than can be represented in 32 bits will be rejected with 6223 this same error. 6225 ERRORS 6227 NFS4ERR_PERM 6229 NFS4ERR_IO 6231 NFS4ERR_ACCES 6233 NFS4ERR_INVAL 6235 NFS4ERR_FBIG 6237 NFS4ERR_NOSPC 6239 NFS4ERR_ROFS 6241 NFS4ERR_DQUOT 6243 NFS4ERR_STALE 6245 NFS4ERR_BADHANDLE 6247 NFS4ERR_NOTSUPP 6249 NFS4ERR_SERVERFAULT 6251 Draft Protocol Specification NFS version 4 October 1999 6253 NFS4ERR_JUKEBOX 6255 NFS4ERR_DENIED 6257 NFS4ERR_GRACE 6259 NFS4ERR_FHEXPIRED 6261 NFS4ERR_WRONGSEC 6263 NFS4ERR_MOVED 6265 Draft Protocol Specification NFS version 4 October 1999 6267 12.2.31. Operation 32: SETCLIENTID - Negotiated Clientid 6269 SYNOPSIS 6271 verifier, client -> clientid 6273 ARGUMENT 6275 struct cid { 6276 opaque verifier[4]; 6277 opaque id<>; 6278 }; 6280 union nfs_client_id switch (clientid4 clientid) { 6281 case 0: 6282 cid ident; 6283 default: 6284 void; 6285 }; 6287 struct SETCLIENTID4args { 6288 seqid4 seqid; 6289 nfs_client_id client; 6290 }; 6292 RESULT 6294 union SETCLIENTID4res switch (nfsstat4 status) { 6295 case NFS4_OK: 6296 clientid4 clientid; 6297 default: 6298 void; 6299 }; 6301 DESCRIPTION 6303 The SETCLIENTID procedure introduces the ability of the client to 6304 notify the server of its intention to use a particular client 6305 identifier and verifier pair. Upon successful completion the 6306 server will return a clientid which is used in subsequent file 6307 locking requests. 6309 Draft Protocol Specification NFS version 4 October 1999 6311 IMPLEMENTATION 6313 The server takes the verifier and client identification supplied 6314 and search for a match of the client identification. If no match 6315 is found the server saves the principal/uid information along with 6316 the verifier and client identification and returns a unique 6317 clientid that is used as a short hand reference to the supplied 6318 information. 6320 If the server find matching client identification and a 6321 corresponding match in principal/uid, the server releases all 6322 locking state for the client and returns a new clientid. 6324 ERRORS 6326 NFS4ERR_INVAL 6328 NFS4ERR_SERVERFAULT 6330 NFS4ERR_CLID_INUSE 6332 Draft Protocol Specification NFS version 4 October 1999 6334 12.2.32. Operation 33: VERIFY - Verify Same Attributes 6336 SYNOPSIS 6338 (cfh), attrbits, attrvals -> - 6340 ARGUMENT 6342 struct VERIFY4args { 6343 /* CURRENT_FH: object */ 6344 bitmap4 attr_request; 6345 fattr4 obj_attributes; 6346 }; 6348 RESULT 6350 struct VERIFY4res { 6351 nfsstat4 status; 6352 }; 6354 DESCRIPTION 6356 The VERIFY procedure is used to verify that attributes have a value 6357 assumed by the client before proceeding with following operations 6358 in the compound request. For instance, a VERIFY can be used to 6359 make sure that the file size has not changed for an append-mode 6360 write: 6362 1. PUTFH 0x0123456 6363 2. VERIFY attrbits attrs 6364 3. WRITE 450328 4096 6366 If the attributes are not as expected, then the request fails and 6367 the data is not appended to the file. 6369 IMPLEMENTATION 6371 ERRORS 6373 Draft Protocol Specification NFS version 4 October 1999 6375 NFS4ERR_ACCES 6377 NFS4ERR_INVAL 6379 NFS4ERR_STALE 6381 NFS4ERR_BADHANDLE 6383 NFS4ERR_NOTSUPP 6385 NFS4ERR_SERVERFAULT 6387 NFS4ERR_JUKEBOX 6389 NFS4ERR_FHEXPIRED 6391 NFS4ERR_MOVED 6393 Draft Protocol Specification NFS version 4 October 1999 6395 12.2.33. Operation 34: WRITE - Write to File 6397 SYNOPSIS 6399 (cfh), offset, count, stability, stateid, data -> count, committed, 6400 verifier 6402 ARGUMENT 6404 enum stable_how4 { 6405 UNSTABLE4 = 0, 6406 DATA_SYNC4 = 1, 6407 FILE_SYNC4 = 2 6408 }; 6410 struct WRITE4args { 6411 /* CURRENT_FH: file */ 6412 stateid4 stateid; 6413 offset4 offset; 6414 count4 count; 6415 stable_how4 stable; 6416 opaque data<>; 6417 }; 6419 RESULT 6421 struct WRITE4resok { 6422 count4 count; 6423 stable_how4 committed; 6424 writeverf4 verf; 6425 }; 6427 union WRITE4res switch (nfsstat4 status) { 6428 case NFS4_OK: 6429 WRITE4resok resok4; 6430 default: 6431 void; 6432 }; 6434 DESCRIPTION 6436 The WRITE procedure is used to write data to a regular file. The 6438 Draft Protocol Specification NFS version 4 October 1999 6440 target file is specified by the current filehandle. The offset 6441 specifies the offset where the data should be written. An offset 6442 of 0 (zero) specifies that the write should start at the beginning 6443 of the file. The count represents the number of bytes of data that 6444 are to be written. If the count is 0 (zero), the WRITE will 6445 succeed and return a count of 0 (zero) subject to permissions 6446 checking. The server may choose to write fewer bytes than 6447 requested by the client. 6449 Part of the write request is a specification of how the write is to 6450 be performed. The client specifies with the stable parameter the 6451 method of how the data is to be processed by the server. If stable 6452 is FILE_SYNC, the server must commit the data written plus all file 6453 system metadata to stable storage before returning results. This 6454 corresponds to the NFS version 2 protocol semantics. Any other 6455 behavior constitutes a protocol violation. If stable is DATA_SYNC, 6456 then the server must commit all of the data to stable storage and 6457 enough of the metadata to retrieve the data before returning. The 6458 server implementor is free to implement DATA_SYNC in the same 6459 fashion as FILE_SYNC, but with a possible performance drop. If 6460 stable is UNSTABLE, the server is free to commit any part of the 6461 data and the metadata to stable storage, including all or none, 6462 before returning a reply to the client. There is no guarantee 6463 whether or when any uncommitted data will subsequently be committed 6464 to stable storage. The only guarantees made by the server are that 6465 it will not destroy any data without changing the value of verf and 6466 that it will not commit the data and metadata at a level less than 6467 that requested by the client. 6469 The stateid returned from a previous record lock or share 6470 reservation request is provided as part of the argument. The 6471 stateid is used by the server to verify that the associated lock is 6472 still valid and to update lease timeouts for the client. 6474 Upon successful completion, the following results are returned. 6475 The count result is the number of bytes of data written to the 6476 file. The server may write fewer bytes than requested. If so, the 6477 actual number of bytes written starting at location, offset, is 6478 returned. 6480 The server also returns an indication of the level of commitment of 6481 the data and metadata via committed. If the server committed all 6482 data and metadata to stable storage, committed should be set to 6483 FILE_SYNC. If the level of commitment was at least as strong as 6484 DATA_SYNC, then committed should be set to DATA_SYNC. Otherwise, 6485 committed must be returned as UNSTABLE. If stable was FILE_SYNC, 6486 then committed must also be FILE_SYNC: anything else constitutes a 6487 protocol violation. If stable was DATA_SYNC, then committed may be 6489 Draft Protocol Specification NFS version 4 October 1999 6491 FILE_SYNC or DATA_SYNC: anything else constitutes a protocol 6492 violation. If stable was UNSTABLE, then committed may be either 6493 FILE_SYNC, DATA_SYNC, or UNSTABLE. 6495 The final portion of the result is the write verifier, verf. The 6496 write verifier is a cookie that the client can use to determine 6497 whether the server has changed state between a call to WRITE and a 6498 subsequent call to either WRITE or COMMIT. This cookie must be 6499 consistent during a single instance of the NFS version 4 protocol 6500 service and must be unique between instances of the NFS version 4 6501 protocol server, where uncommitted data may be lost. 6503 If a client writes data to the server with the stable argument set 6504 to UNSTABLE and the reply yields a committed response of DATA_SYNC 6505 or UNSTABLE, the client will follow up some time in the future with 6506 a COMMIT operation to synchronize outstanding asynchronous data and 6507 metadata with the server's stable storage, barring client error. It 6508 is possible that due to client crash or other error that a 6509 subsequent COMMIT will not be received by the server. 6511 IMPLEMENTATION 6513 It is possible for the server to write fewer than count bytes of 6514 data. In this case, the server should not return an error unless no 6515 data was written at all. If the server writes less than count 6516 bytes, the client should issue another WRITE to write the remaining 6517 data. 6519 It is assumed that the act of writing data to a file will cause the 6520 time_modified of the file to be updated. However, the time_modified 6521 of the file should not be changed unless the contents of the file 6522 are changed. Thus, a WRITE request with count set to 0 should not 6523 cause the time_modified of the file to be updated. 6525 The definition of stable storage has been historically a point of 6526 contention. The following expected properties of stable storage may 6527 help in resolving design issues in the implementation. Stable 6528 storage is persistent storage that survives: 6530 1. Repeated power failures. 6531 2. Hardware failures (of any board, power supply, etc.). 6532 3. Repeated software crashes, including reboot cycle. 6534 This definition does not address failure of the stable storage 6535 module itself. 6537 Draft Protocol Specification NFS version 4 October 1999 6539 The verifier, is defined to allow a client to detect different 6540 instances of an NFS version 4 protocol server over which cached, 6541 uncommitted data may be lost. In the most likely case, the verifier 6542 allows the client to detect server reboots. This information is 6543 required so that the client can safely determine whether the server 6544 could have lost cached data. If the server fails unexpectedly and 6545 the client has uncommitted data from previous WRITE requests (done 6546 with the stable argument set to UNSTABLE and in which the result 6547 committed was returned as UNSTABLE as well) it may not have flushed 6548 cached data to stable storage. The burden of recovery is on the 6549 client and the client will need to retransmit the data to the 6550 server. 6552 A suggested verifier would be to use the time that the server was 6553 booted or the time the server was last started (if restarting the 6554 server without a reboot results in lost buffers). 6556 The committed field in the results allows the client to do more 6557 effective caching. If the server is committing all WRITE requests 6558 to stable storage, then it should return with committed set to 6559 FILE_SYNC, regardless of the value of the stable field in the 6560 arguments. A server that uses an NVRAM accelerator may choose to 6561 implement this policy. The client can use this to increase the 6562 effectiveness of the cache by discarding cached data that has 6563 already been committed on the server. 6565 Some implementations may return NFS4ERR_NOSPC instead of 6566 NFS4ERR_DQUOT when a user's quota is exceeded. 6568 ERRORS 6570 NFS4ERR_IO 6572 NFS4ERR_ACCES 6574 NFS4ERR_INVAL 6576 NFS4ERR_FBIG 6578 NFS4ERR_NOSPC 6580 NFS4ERR_ROFS 6582 NFS4ERR_DQUOT 6584 NFS4ERR_STALE 6586 Draft Protocol Specification NFS version 4 October 1999 6588 NFS4ERR_BADHANDLE 6590 NFS4ERR_SERVERFAULT 6592 NFS4ERR_JUKEBOX 6594 NFS4ERR_LOCKED 6596 NFS4ERR_GRACE 6598 NFS4ERR_FHEXPIRED 6600 NFS4ERR_WRONGSEC 6602 NFS4ERR_MOVED 6604 Draft Protocol Specification NFS version 4 October 1999 6606 13. NFS Version 4 Callback Procedures 6608 The procedures used for callbacks are defined in the following 6609 sections. In the interest of clarity, the terms "client" and 6610 "server" refer to NFS clients and servers, despite the fact that for 6611 an individual callback RPC, the sense of these terms would be 6612 precisely the opposite. 6614 13.1. Procedure 0: CB_NULL - No Operation 6616 SYNOPSIS 6618 6620 ARGUMENT 6622 void; 6624 RESULT 6626 void; 6628 DESCRIPTION 6630 Standard ONCRPC NULL procedure. Void argument, void response. 6632 ERRORS 6634 None. 6636 Draft Protocol Specification NFS version 4 October 1999 6638 13.2. Procedure 1: CB_COMPOUND - Compound Operations 6640 SYNOPSIS 6642 compoundargs -> compoundres 6644 ARGUMENT 6646 union cb_opunion switch (unsigned opcode) { 6647 case : ; 6648 ... 6649 }; 6651 struct cb_op { 6652 cb_opunion ops; 6653 }; 6655 struct CB_COMPOUND4args { 6656 utf8string tag; 6657 cb_op oplist<>; 6658 }; 6660 RESULT 6662 union cb_resultdata switch (unsigned resop){ 6663 case ; 6664 ... 6665 }; 6667 struct CB_COMPOUND4res { 6668 nfsstat4 status; 6669 utf8string tag; 6670 cb_resultdata data<>; 6671 }; 6673 union opunion switch (unsigned opcode) { 6674 case : ; 6675 ... 6676 }; 6678 struct op { 6679 opunion ops; 6680 }; 6682 struct COMPOUND4args { 6684 Draft Protocol Specification NFS version 4 October 1999 6686 utf8string tag; 6687 op oplist<>; 6688 }; 6690 DESCRIPTION 6692 The CB_COMPOUND procedure is used to combine one or more of the 6693 callback procedures into a single RPC request. The main callback 6694 RPC program has two main procedures: CB_NULL and CB_COMPOUND. All 6695 other procedures use the CB_COMPOUND procedure as a wrapper. 6697 In the processing of the CB_COMPOUND procedure, the server may find 6698 that it does not have the available resources to execute any or all 6699 of the procedures within the CB_COMPOUND sequence. In this case, 6700 the error NFS4ERR_RESOURCE will be returned for the particular 6701 procedure within the CB_COMPOUND operation where the resource 6702 exhaustion occurred. This assumes that all previous procedures 6703 within the CB_COMPOUND sequence have been evaluated successfully. 6705 IMPLEMENTATION 6707 The CB_COMPOUND procedure is used to combine individual procedures 6708 into a single RPC request. The server interprets each of the 6709 procedures in turn. If a procedure is executed by the server and 6710 the status of that procedure is NFS4_OK, then the next procedure in 6711 the CB_COMPOUND procedure is executed. The server continues this 6712 process until there are no more procedures to be executed or one of 6713 the procedures has a status value other than NFS4_OK. 6715 ERRORS 6717 NFS4ERR_RESOURCE 6719 Draft Protocol Specification NFS version 4 October 1999 6721 13.2.1. Procedure 2: CB_GETATTR - Get Attributes 6723 SYNOPSIS 6725 fh, attrbits -> attrbits, attrvals 6727 ARGUMENT 6729 struct CB_GETATTR4args { 6730 nfs_fh4 fh; 6731 bitmap4 attr_request; 6732 }; 6734 RESULT 6736 struct CB_GETATTR4resok { 6737 fattr4 obj_attributes; 6738 }; 6740 union CB_GETATTR4res switch (nfsstat4 status) { 6741 case NFS4_OK: 6742 CB_GETATTR4resok resok4; 6743 default: 6744 void; 6745 }; 6747 DESCRIPTION 6749 CB_GETATTR is used to obtain the attributes modified by an open 6750 delegate to allow the server to respond to GETATTR requests for a 6751 file which is the subject of an open delegation. 6753 IMPLEMENTATION 6755 The client returns attrbits and the associated attribute values 6756 only for attributes that it may change (change, time_modify, 6757 object_size). It may further limit the response to attributes that 6758 it has in fact changed during the scope of the delegation. 6760 Draft Protocol Specification NFS version 4 October 1999 6762 ERRORS 6764 6766 Draft Protocol Specification NFS version 4 October 1999 6768 13.2.2. Procedure 3: CB_RECALL - Recall an Open Delegation 6770 SYNOPSIS 6772 stateid, truncate, fh 6774 ARGUMENT 6776 struct CB_RECALL4args { 6777 stateid4 stateid; 6778 bool truncate; 6779 nfs_fh4 fh; 6780 }; 6782 RESULT 6784 struct CB_RECALL4res { 6785 nfsstat4 status; 6786 }; 6788 DESCRIPTION 6790 CB_RECALL is used to begin the process of recalling an open 6791 delegation and returning it to the server. 6793 The truncate flag is used to optimize recall for a file which is 6794 about to be truncated to zero. When it is set, the client is freed 6795 of obligation to propagate modified data for the file to the 6796 server, since this data is irrelevant. 6798 IMPLEMENTATION 6800 The client should reply to the callback immediately. Replying does 6801 not complete the recall. The recall is not complete until the 6802 delegation is returned using a DELEGRETURN. 6804 ERRORS 6806 Draft Protocol Specification NFS version 4 October 1999 6808 6810 Draft Protocol Specification NFS version 4 October 1999 6812 14. Locking notes 6814 14.1. Short and long leases 6816 The usual lease trade-offs apply: short leases are good for fast 6817 server recovery at a cost of increased RENEW or READ (with zero 6818 length) requests. 6820 Longer leases are certainly kinder and gentler to large internet 6821 servers trying to handle huge numbers of clients. RENEW requests drop 6822 in direct proportion to the lease time. The disadvantages of long 6823 leases are slower server recover after crash (server must wait for 6824 leases to expire and grace period before granting new lock requests) 6825 and increased file contention (if client fails to transmit an unlock 6826 request then server must wait for lease expiration before granting 6827 new locks). 6829 Long leases are usable if the server is to store lease state in non- 6830 volatile memory. Upon recovery, the server can reconstruct the lease 6831 state from its non-volatile memory and continue operation with its 6832 clients and therefore long leases are not an issue. 6834 14.2. Clocks and leases 6836 To avoid the need for synchronized clocks, lease times are granted by 6837 the server as a time delta, though there is a requirement that the 6838 client and server clocks do not drift excessively over the duration 6839 of the lock. There is also the issue of propagation delay across the 6840 network which could easily be several hundred milliseconds across the 6841 Internet as well as the possibility that requests will be lost and 6842 need to be retransmitted. 6844 To take propagation delay into account, the client should subtract a 6845 it from lease times, e.g. if the client estimates the one-way 6846 propagation delay as 200 msec, then it can assume that the lease is 6847 already 200 msec old when it gets it. In addition, it'll take 6848 another 200 msec to get a response back to the server. So the client 6849 must send a lock renewal or write data back to the server 400 msec 6850 before the lease would expire. 6852 The client could measure propagation delay with reasonable accuracy 6853 by measuring the round-trip time for lock extensions assuming that 6854 there's not much server processing overhead in an extension. 6856 14.3. Locks and lease times 6858 Lock requests do not contain desired lease times. The server 6860 Draft Protocol Specification NFS version 4 October 1999 6862 allocates leases with no information from the client. The assumption 6863 here is that the client really has no idea of just how long the lock 6864 will be required. If a scenario can be found where a hint from the 6865 client as to the maximum lease time desired would be useful, then 6866 this feature could be added to lock requests. 6868 14.4. Locking of directories and other meta-files 6870 A question: should directories and/or other file-system objects like 6871 symbolic links be lockable ? Clients will want to cache whole 6872 directories. It would be nice to have consistent directory caches, 6873 but it would require that any client creating a new file get a write 6874 lock on the directory and be prepared to handle lock denial. Is the 6875 weak cache consistency that we currently have for directories 6876 acceptable ? I think perhaps it is - given the expense of doing full 6877 consistency on an Internet scale. 6879 14.5. Proxy servers and leases 6881 Proxy servers. There is some interest in having NFS V4 support 6882 caching proxies. Support for proxy caching is a requirement if 6883 servers are to handle large numbers of clients - clients that may 6884 have little or no ability to cache on their own. How could proxy 6885 servers use lease-based locking ? 6887 14.6. Locking and the new latency 6889 Latency caused by locking. If a client wants to update a file then 6890 it will have to wait until the leases on read locks have expired. If 6891 the leases are of the order of 60 seconds or several minutes then the 6892 client (and end-user) may be blocked for a while. This is unfamiliar 6893 for current NFS users who are not bothered by mandatory locking - but 6894 it could be an issue if we decide we like the caching benefits. A 6895 similar problem exists for clients that wish to read a file that is 6896 write locked. The read-lock case is likely to be more common if 6897 read-locking is used to protect cached data on the client. 6899 Draft Protocol Specification NFS version 4 October 1999 6901 15. Internationalization 6903 The primary issue in which NFS needs to deal with 6904 internationalization, or i18n, is with respect to file names and 6905 other strings as used within the protocol. NFS' choice of string 6906 representation must allow reasonable name/string access to clients 6907 which use various languages. The UTF-8 encoding allows for this type 6908 of access and this choice is explained in the following. 6910 15.1. Universal Versus Local Character Sets 6912 [RFC1345] describes a table of 16 bit characters for many different 6913 languages (the bit encodings match Unicode, though of course RFC1345 6914 is somewhat out of date with respect to current Unicode assignments). 6915 Each character from each language has a unique 16 bit value in the 16 6916 bit character set. Thus this table can be thought of as a universal 6917 character set. [RFC1345] then talks about groupings of subsets of the 6918 entire 16 bit character set into "Charset Tables". For example one 6919 might take all the Greek characters from the 16 bit table (which are 6920 are consecutively allocated), and normalize their offsets to a table 6921 that fits in 7 bits. Thus we find that "lower case alpha" is in the 6922 same position as "upper case a" in the US-ASCII table, and "upper 6923 case alpha" is in the same position as "lower case a" in the US-ASCII 6924 table. 6926 These normalized subset character sets can be thought of as "local 6927 character sets", suitable for an operating system locale. 6929 Local character sets are not suitable for the NFS protocol. Consider 6930 someone who creates a file with a name in a Swedish character set. If 6931 someone else later goes to access the file with their locale set to 6932 the Swedish language, then there are no problems. But if someone in 6933 say the US-ASCII locale goes to access the file, the file name will 6934 look very different, because the Swedish characters in the 7 bit 6935 table will now be represented in US-ASCII characters on the display. 6936 It would be preferable to give the US-ASCII user a way to display the 6937 file name using Swedish glyphs. In order to do that, the NFS protocol 6938 would have to include the locale with the file name on each operation 6939 to create a file. 6941 But then what of the situation when we have a path name on the server 6942 like: 6944 /component-1/component-2/component-3 6946 Each component could have been created with a different locale. If 6947 one issues CREATE with multi-component path name, and if some of the 6948 leading components already exist, what is to be done with the 6950 Draft Protocol Specification NFS version 4 October 1999 6952 existing components? Is the current locale attribute replaced with 6953 the user's current one? These types of situations quickly become too 6954 complex when there is an alternate solution. 6956 If NFS V4 used a universal 16 bit or 32 bit character set (or a 6957 encoding of a 16 bit or 32 bit character set into octets), then 6958 server and client need not care if the locale of the user accessing 6959 the file is different than the locale of the user who created the 6960 file. The unique 16 bit or 32 bit encoding of the character allows 6961 for determination of what language the character is from and also how 6962 to display that character on the client. The server need not know 6963 what locales are used. 6965 15.2. Overview of Universal Character Set Standards 6967 The previous section makes a case for using a universal character set 6968 in NFS version 4. This section makes the case for using UTF-8 as the 6969 specific universal character set for NFS version 4. 6971 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 6972 Unicode, and UCS-*. There are two standards bodies managing universal 6973 code sets: 6975 o ISO/IEC which has the standard 10646-1 6977 o Unicode which has the Unicode standard 6979 Both standards bodies have pledged to track each other's assignments 6980 of character codes. 6982 The following is a brief analysis of the various standards. 6984 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 6985 multi-octet character set called the Universal Character 6986 Set (UCS), which encompasses most of the world's writing 6987 systems." 6989 UCS-2 a two octet per character encoding that addresses the first 6990 2^16 characters of UCS. Currently there are no UCS 6991 characters beyond that range. 6993 UCS-4 a four octet per character encoding that permits the 6994 encoding of up to 2^31 characters. 6996 Draft Protocol Specification NFS version 4 October 1999 6998 UTF UCS transformation format. 7000 UTF-1 Only historical interest; it has been removed from 10646-1 7002 UTF-7 Encodes the entire "repertoire" of UCS "characters using 7003 only octets with the higher order bit clear". [RFC2152] 7004 describes UTF-7. UTF-7 accomplishes this by reserving one 7005 of the 7bit US-ASCII characters as a "shift" character to 7006 indicate non-US-ASCII characters. 7008 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 7009 characters are encoded as before unchanged. Any octet with 7010 the high bit cleared can only mean a US-ASCII character. 7011 The high bit set means that a UCS character is being 7012 encoded. 7014 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 7015 reserved range in UCS-2. 7017 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 7019 Up to the present time, changes in Unicode and amendments 7020 to ISO/IEC 10646 have tracked each other, so that the 7021 character repertoires and code point assignments have 7022 remained in sync. The relevant standardization committees 7023 have committed to maintain this very useful synchronism. 7025 15.3. Difficulties with UCS-4, UCS-2, Unicode 7027 Adapting existing applications, and file systems to multi-octet 7028 schemes like UCS and Unicode can be difficult. A significant amount 7029 of code has been written to process streams of bytes. Also there are 7030 many existing stored objects described with 7 bit or 8 bit 7031 characters. Doubling or quadrupling the bandwidth and storage 7032 requirements seems like an expensive way to accomplish I18N. 7034 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 7035 enough but, according to [Unicode1], 38,887 Unicode characters are 7036 already assigned. And according to [Unicode2] there are still more 7037 languages that need to be added. 7039 Draft Protocol Specification NFS version 4 October 1999 7041 15.4. UTF-8 and its solutions 7043 UTF-8 solves problems for NFS that exist with the use of UCS and 7044 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 7045 that will be compact for most users. The encoding table from UCS-4 to 7046 UTF-8, as copied from [RFC2279]: 7048 UCS-4 range (hex.) UTF-8 octet sequence (binary) 7049 0000 0000-0000 007F 0xxxxxxx 7050 0000 0080-0000 07FF 110xxxxx 10xxxxxx 7051 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 7053 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 7054 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 7055 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 7056 10xxxxxx 7058 See [RFC2279] for precise encoding and decoding rules. Note because 7059 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 7060 for the reserved range between D800 and DFFF. 7062 Note that the 16 bit UCS or Unicode characters require no more than 3 7063 octets to encode into UTF-8 7065 Interestingly, UTF-8 has room to handle characters larger than 31 7066 bits, because the leading octet of form: 7068 1111111x 7070 is not defined. If needed, ISO could either use that octet to 7071 indicate a sequence of an encoded 8 octet character, or perhaps use 7072 11111110 to permit the next octet to indicate an even more expandable 7073 character set. 7075 So using UTF-8 to represent character encodings means never having to 7076 run out of room. 7078 Draft Protocol Specification NFS version 4 October 1999 7080 16. Security Considerations 7082 The major security feature to consider is the authentication of the 7083 user making the request of NFS service. Consideration should also be 7084 given to the integrity and privacy of this NFS request. These 7085 specific issues are discussed as part of the section on "RPC and 7086 Security Flavor". 7088 As this document progresses, other issues of denial of service and 7089 other typical security issues will be addressed here along with those 7090 issues specific to NFS service. 7092 Draft Protocol Specification NFS version 4 October 1999 7094 17. NFS Version 4 RPC definition file 7096 /* 7097 * Copyright (C) The Internet Society (1998,1999). 7098 * All Rights Reserved. 7099 */ 7101 /* 7102 * nfs4_prot.x 7103 * 7104 */ 7106 %#pragma ident "%W% %D%" 7108 /* 7109 * Basic typedefs for RFC 1832 data type definitions 7110 */ 7111 typedef unsigned hyper uint64_t; 7112 typedef hyper int64_t; 7113 typedef unsigned int uint32_t; 7114 typedef int int32_t; 7116 /* 7117 * Sizes 7118 */ 7119 const NFS4_FHSIZE = 128; 7120 const NFS4_CREATEVERFSIZE = 8; 7122 /* 7123 * File types 7124 */ 7125 enum nfs_ftype4 { 7126 NF4REG = 1, /* Regular File */ 7127 NF4DIR = 2, /* Directory */ 7128 NF4BLK = 3, /* Special File - block device */ 7129 NF4CHR = 4, /* Special File - character device */ 7130 NF4LNK = 5, /* Symbolic Link */ 7131 NF4SOCK = 6, /* Special File - socket */ 7132 NF4FIFO = 7, /* Special File - fifo */ 7133 NF4ATTRDIR = 8, /* Attribute Directory */ 7134 NF4NAMEDATTR = 9 /* Named Attribute */ 7135 }; 7137 /* 7138 * Error status 7139 */ 7140 enum nfsstat4 { 7141 NFS4_OK = 0, 7143 Draft Protocol Specification NFS version 4 October 1999 7145 NFS4ERR_PERM = 1, 7146 NFS4ERR_NOENT = 2, 7147 NFS4ERR_IO = 5, 7148 NFS4ERR_NXIO = 6, 7149 NFS4ERR_ACCES = 13, 7150 NFS4ERR_EXIST = 17, 7151 NFS4ERR_XDEV = 18, 7152 NFS4ERR_NODEV = 19, 7153 NFS4ERR_NOTDIR = 20, 7154 NFS4ERR_ISDIR = 21, 7155 NFS4ERR_INVAL = 22, 7156 NFS4ERR_FBIG = 27, 7157 NFS4ERR_NOSPC = 28, 7158 NFS4ERR_ROFS = 30, 7159 NFS4ERR_MLINK = 31, 7160 NFS4ERR_NAMETOOLONG = 63, 7161 NFS4ERR_NOTEMPTY = 66, 7162 NFS4ERR_DQUOT = 69, 7163 NFS4ERR_STALE = 70, 7164 NFS4ERR_BADHANDLE = 10001, 7165 NFS4ERR_NOT_SYNC = 10002, 7166 NFS4ERR_BAD_COOKIE = 10003, 7167 NFS4ERR_NOTSUPP = 10004, 7168 NFS4ERR_TOOSMALL = 10005, 7169 NFS4ERR_SERVERFAULT = 10006, 7170 NFS4ERR_BADTYPE = 10007, 7171 NFS4ERR_JUKEBOX = 10008, 7172 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 7173 NFS4ERR_DENIED = 10010,/* lock unavailable */ 7174 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 7175 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 7176 NFS4ERR_GRACE = 10013,/* in grace period */ 7177 NFS4ERR_FHEXPIRED = 10014,/* file handle expired */ 7178 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 7179 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 7180 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 7181 NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ 7182 NFS4ERR_MOVED = 10019,/* filesystem relocated */ 7183 NFS4ERR_NOFILEHANDLE = 10020 /* current FH is not set */ 7184 }; 7186 /* 7187 * Basic data types 7188 */ 7189 typedef uint32_t bitmap4<>; 7190 typedef uint64_t offset4; 7191 typedef uint32_t count4; 7192 typedef uint32_t length4; 7194 Draft Protocol Specification NFS version 4 October 1999 7196 typedef uint64_t clientid4; 7197 typedef uint64_t stateid4; 7198 typedef uint32_t seqid4; 7199 typedef opaque utf8string<>; 7200 typedef utf8string component4; 7201 typedef component4 pathname4<>; 7202 typedef uint64_t nfs_lockid4; 7203 typedef uint32_t nfs_lease4; 7204 typedef uint32_t nfs_lockstate4; 7205 typedef uint64_t nfs_cookie4; 7206 typedef utf8string linktext4; 7207 typedef opaque sec_oid4<>; 7208 typedef uint32_t qop4; 7209 typedef uint32_t mode4; 7210 typedef uint32_t writeverf4; 7211 typedef opaque createverf4[NFS4_CREATEVERFSIZE]; 7213 /* 7214 * Timeval 7215 */ 7216 struct nfstime4 { 7217 int64_t seconds; 7218 uint32_t nseconds; 7219 }; 7221 /* 7222 * File access handle 7223 */ 7224 typedef opaque nfs_fh4; 7226 /* 7227 * File attribute definitions 7228 */ 7230 /* 7231 * FSID structure for major/minor 7232 */ 7233 struct fsid4 { 7234 uint64_t major; 7235 uint64_t minor; 7236 }; 7238 /* 7239 * Filesystem locations attribute for relocation/migration 7240 */ 7241 struct fs_location4 { 7242 utf8string server<>; 7244 Draft Protocol Specification NFS version 4 October 1999 7246 pathname4 rootpath; 7247 }; 7249 struct fs_locations4 { 7250 pathname4 fs_root; 7251 fs_location4 locations<>; 7252 }; 7254 /* 7255 * Various Access Control Entry definitions 7256 */ 7258 /* 7259 * Mask that indicates which Access Control Entries are supported. 7260 * Values for the fattr4_aclsupport attribute. 7261 */ 7262 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 7263 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 7264 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 7265 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 7267 typedef uint32_t acetype4; 7269 /* 7270 * acetype4 values, others can be added as needed. 7271 */ 7272 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 7273 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 7274 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 7275 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 7277 /* 7278 * ACE flag 7279 */ 7280 typedef uint32_t aceflag4; 7282 /* 7283 * ACE flag values 7284 */ 7285 const ACE4_FILE_INHERIT_ACE = 0x00000001; 7286 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 7287 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 7288 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 7289 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 7290 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 7291 const ACE4_IDENTIFIER_GROUP = 0x00000040; 7293 Draft Protocol Specification NFS version 4 October 1999 7295 /* 7296 * ACE mask 7297 */ 7298 typedef uint32_t acemask4; 7300 /* 7301 * ACE mask values 7302 */ 7303 const ACE4_READ_DATA = 0x00000001; 7304 const ACE4_LIST_DIRECTORY = 0x00000001; 7305 const ACE4_WRITE_DATA = 0x00000002; 7306 const ACE4_ADD_FILE = 0x00000002; 7307 const ACE4_APPEND_DATA = 0x00000004; 7308 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 7309 const ACE4_READ_STREAMS = 0x00000008; 7310 const ACE4_WRITE_STREAMS = 0x00000010; 7311 const ACE4_EXECUTE = 0x00000020; 7312 const ACE4_DELETE_CHILD = 0x00000040; 7313 const ACE4_READ_ATTRIBUTES = 0x00000080; 7314 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 7316 const ACE4_READ_CONTROL = 0x00000200; 7317 const ACE4_READ_EXTENDED_ATTRIBUTES = 0x00000400; 7318 const ACE4_WRITE_EXTENDED_ATTRIBUTES = 0x00000800; 7320 const ACE4_DELETE = 0x00010000; 7321 const ACE4_READ_ACL = 0x00020000; 7322 const ACE4_WRITE_ACL = 0x00040000; 7323 const ACE4_WRITE_OWNER = 0x00080000; 7324 const ACE4_SYNCHRONIZE = 0x00100000; 7326 /* 7327 * ACE4_GENERIC_READ -- defined as combination of 7328 * ACE4_READ_CONTROL | 7329 * ACE4_READ_DATA | 7330 * ACE4_READ_ATTRIBUTES | 7331 * ACE4_READ_EXTENDED_ATTRIBUTES | 7332 * ACE4_SYNCHRONIZE 7333 */ 7335 const ACE4_GENERIC_READ = 0x00100681; 7337 /* 7338 * ACE4_GENERIC_WRITE -- defined as combination of 7339 * ACE4_READ_CONTROL | 7340 * ACE4_WRITE_DATA | 7341 * ACE4_WRITE_ATTRIBUTES | 7342 * ACE4_WRITE_EXTENDED_ATTRIBUTES | 7344 Draft Protocol Specification NFS version 4 October 1999 7346 * ACE4_APPEND_DATA | 7347 * ACE4_SYNCHRONIZE 7348 */ 7349 const ACE4_GENERIC_WRITE = 0x00100B06; 7351 /* 7352 * ACE4_GENERIC_EXECUTE -- defined as combination of 7353 * ACE4_READ_CONTROL 7354 * ACE4_READ_ATTRIBUTES 7355 * ACE4_EXECUTE 7356 * ACE4_SYNCHRONIZE 7357 */ 7358 const ACE4_GENERIC_EXECUTE = 0x001002A0; 7360 /* 7361 * Access Control Entry definition 7362 */ 7363 struct nfsace4 { 7364 acetype4 type; 7365 aceflag4 flag; 7366 acemask4 access_mask; 7367 utf8string who; 7368 }; 7370 /* 7371 * Special data/attribute associated with 7372 * file types NF4BLK and NF4CHR. 7373 */ 7374 struct specdata4 { 7375 uint32_t specdata1; 7376 uint32_t specdata2; 7377 }; 7379 typedef bitmap4 fattr4_supported_attrs; 7380 typedef nfs_ftype4 fattr4_type; 7381 typedef bool fattr4_persistent_fh; 7382 typedef uint64_t fattr4_change; 7383 typedef uint64_t fattr4_size; 7384 typedef bool fattr4_link_support; 7385 typedef bool fattr4_symlink_support; 7386 typedef bool fattr4_named_attr; 7387 typedef fsid4 fattr4_fsid; 7388 typedef bool fattr4_unique_handles; 7389 typedef uint32_t fattr4_lease_time; 7390 typedef nfsstat4 fattr4_rdattr_error; 7392 Draft Protocol Specification NFS version 4 October 1999 7394 typedef nfsace4 fattr4_acl<>; 7395 typedef uint32_t fattr4_aclsupport; 7396 typedef bool fattr4_archive; 7397 typedef bool fattr4_cansettime; 7398 typedef bool fattr4_case_insensitive; 7399 typedef bool fattr4_case_preserving; 7400 typedef bool fattr4_chown_restricted; 7401 typedef uint64_t fattr4_fileid; 7402 typedef uint64_t fattr4_files_avail; 7403 typedef nfs_fh4 fattr4_filehandle; 7404 typedef uint64_t fattr4_files_free; 7405 typedef uint64_t fattr4_files_total; 7406 typedef fs_locations4 fattr4_fs_locations; 7407 typedef bool fattr4_hidden; 7408 typedef bool fattr4_homogeneous; 7409 typedef uint64_t fattr4_maxfilesize; 7410 typedef uint32_t fattr4_maxlink; 7411 typedef uint32_t fattr4_maxname; 7412 typedef uint64_t fattr4_maxread; 7413 typedef uint64_t fattr4_maxwrite; 7414 typedef utf8string fattr4_mimetype; 7415 typedef mode4 fattr4_mode; 7416 typedef bool fattr4_no_trunc; 7417 typedef uint32_t fattr4_numlinks; 7418 typedef utf8string fattr4_owner; 7419 typedef utf8string fattr4_owner_group; 7420 typedef uint64_t fattr4_quota_hard; 7421 typedef uint64_t fattr4_quota_soft; 7422 typedef uint64_t fattr4_quota_used; 7423 typedef specdata4 fattr4_rawdev; 7424 typedef uint64_t fattr4_space_avail; 7425 typedef uint64_t fattr4_space_free; 7426 typedef uint64_t fattr4_space_total; 7427 typedef uint64_t fattr4_space_used; 7428 typedef bool fattr4_system; 7429 typedef nfstime4 fattr4_time_access; 7430 typedef nfstime4 fattr4_time_backup; 7431 typedef nfstime4 fattr4_time_create; 7432 typedef nfstime4 fattr4_time_delta; 7433 typedef nfstime4 fattr4_time_metadata; 7434 typedef nfstime4 fattr4_time_modify; 7435 typedef utf8string fattr4_version; 7436 typedef nfstime4 fattr4_volatility; 7438 /* 7439 * Mandatory Attributes 7440 */ 7442 Draft Protocol Specification NFS version 4 October 1999 7444 const FATTR4_SUPPORTED_ATTRS = 0; 7445 const FATTR4_TYPE = 1; 7446 const FATTR4_PERSISTENT_FH = 2; 7447 const FATTR4_CHANGE = 3; 7448 const FATTR4_SIZE = 4; 7449 const FATTR4_LINK_SUPPORT = 5; 7450 const FATTR4_SYMLINK_SUPPORT = 6; 7451 const FATTR4_NAMED_ATTR = 7; 7452 const FATTR4_FSID = 8; 7453 const FATTR4_UNIQUE_HANDLES = 9; 7454 const FATTR4_LEASE_TIME = 10; 7455 const FATTR4_RDATTR_ERROR = 11; 7457 /* 7458 * Recommended Attributes 7459 */ 7460 const FATTR4_ACL = 12; 7461 const FATTR4_ARCHIVE = 13; 7462 const FATTR4_CANSETTIME = 14; 7463 const FATTR4_CASE_INSENSITIVE = 15; 7464 const FATTR4_CASE_PRESERVING = 16; 7465 const FATTR4_CHOWN_RESTRICTED = 17; 7466 const FATTR4_FILEHANDLE = 18; 7467 const FATTR4_FILEID = 19; 7468 const FATTR4_FILES_AVAIL = 20; 7469 const FATTR4_FILES_FREE = 21; 7470 const FATTR4_FILES_TOTAL = 22; 7471 const FATTR4_FS_LOCATIONS = 23; 7472 const FATTR4_HIDDEN = 24; 7473 const FATTR4_HOMOGENEOUS = 25; 7474 const FATTR4_MAXFILESIZE = 26; 7475 const FATTR4_MAXLINK = 27; 7476 const FATTR4_MAXNAME = 28; 7477 const FATTR4_MAXREAD = 29; 7478 const FATTR4_MAXWRITE = 30; 7479 const FATTR4_MIMETYPE = 31; 7480 const FATTR4_MODE = 32; 7481 const FATTR4_NO_TRUNC = 33; 7482 const FATTR4_NUMLINKS = 34; 7483 const FATTR4_OWNER = 35; 7484 const FATTR4_OWNER_GROUP = 36; 7485 const FATTR4_QUOTA_HARD = 37; 7486 const FATTR4_QUOTA_SOFT = 38; 7487 const FATTR4_QUOTA_USED = 39; 7488 const FATTR4_RAWDEV = 40; 7489 const FATTR4_SPACE_AVAIL = 41; 7490 const FATTR4_SPACE_FREE = 42; 7491 const FATTR4_SPACE_TOTAL = 43; 7493 Draft Protocol Specification NFS version 4 October 1999 7495 const FATTR4_SPACE_USED = 44; 7496 const FATTR4_SYSTEM = 45; 7497 const FATTR4_TIME_ACCESS = 46; 7498 const FATTR4_TIME_BACKUP = 47; 7499 const FATTR4_TIME_CREATE = 48; 7500 const FATTR4_TIME_DELTA = 49; 7501 const FATTR4_TIME_METADATA = 50; 7502 const FATTR4_TIME_MODIFY = 51; 7503 const FATTR4_VERSION = 52; 7504 const FATTR4_VOLATILITY = 53; 7506 typedef opaque attrlist4<>; 7508 /* 7509 * File attribute container 7510 */ 7511 struct fattr4 { 7512 bitmap4 attrmask; 7513 attrlist4 attr_vals; 7514 }; 7516 /* 7517 * Change info for the client 7518 */ 7519 struct change_info4 { 7520 bool atomic; 7521 fattr4_change before; 7522 fattr4_change after; 7523 }; 7525 struct clientaddr4 { 7526 /* see struct rpcb in RFC 1833 */ 7527 string r_netid<>; /* network id */ 7528 string r_addr<>; /* universal address */ 7529 }; 7531 /* 7532 * Callback program info as provided by the client 7533 */ 7534 struct cb_client4 { 7535 unsigned int cb_program; 7536 clientaddr4 cb_location; 7537 }; 7539 /* 7540 * Client ID 7541 */ 7543 Draft Protocol Specification NFS version 4 October 1999 7545 struct nfs_client_id4 { 7546 opaque verifier[4]; 7547 opaque id<>; 7548 }; 7550 struct nfs_lockowner4 { 7551 clientid4 clientid; 7552 opaque owner<>; 7553 }; 7555 enum nfs_lock_type4 { 7556 READ_LT = 1, 7557 WRITE_LT = 2, 7558 READW_LT = 3, /* blocking read */ 7559 WRITEW_LT = 4 /* blocking write */ 7560 }; 7562 /* 7563 * ACCESS: Check access permission 7564 */ 7565 const ACCESS4_READ = 0x0001; 7566 const ACCESS4_LOOKUP = 0x0002; 7567 const ACCESS4_MODIFY = 0x0004; 7568 const ACCESS4_EXTEND = 0x0008; 7569 const ACCESS4_DELETE = 0x0010; 7570 const ACCESS4_EXECUTE = 0x0020; 7572 struct ACCESS4args { 7573 /* CURRENT_FH: object */ 7574 uint32_t access; 7575 }; 7577 struct ACCESS4resok { 7578 uint32_t supported; 7579 uint32_t access; 7580 }; 7582 union ACCESS4res switch (nfsstat4 status) { 7583 case NFS4_OK: 7584 ACCESS4resok resok4; 7585 default: 7586 void; 7587 }; 7589 /* 7590 * CLOSE: Close a file and release share locks 7591 */ 7592 struct CLOSE4args { 7594 Draft Protocol Specification NFS version 4 October 1999 7596 /* CURRENT_FH: object */ 7597 stateid4 stateid; 7598 }; 7600 union CLOSE4res switch (nfsstat4 status) { 7601 case NFS4_OK: 7602 stateid4 stateid; 7603 default: 7604 void; 7605 }; 7607 /* 7608 * COMMIT: Commit cached data on server to stable storage 7609 */ 7610 struct COMMIT4args { 7611 /* CURRENT_FH: file */ 7612 offset4 offset; 7613 count4 count; 7614 }; 7616 struct COMMIT4resok { 7617 writeverf4 verf; 7618 }; 7620 union COMMIT4res switch (nfsstat4 status) { 7621 case NFS4_OK: 7622 COMMIT4resok resok4; 7623 default: 7624 void; 7625 }; 7627 /* 7628 * CREATE: Create a file 7629 */ 7630 union createtype4 switch (nfs_ftype4 type) { 7631 case NF4LNK: 7632 utf8string linkdata; 7633 case NF4BLK: 7634 case NF4CHR: 7635 specdata4 devdata; 7636 case NF4SOCK: 7637 case NF4FIFO: 7638 case NF4DIR: 7639 case NF4ATTRDIR: 7640 void; 7641 }; 7643 Draft Protocol Specification NFS version 4 October 1999 7645 struct CREATE4args { 7646 /* CURRENT_FH: directory for creation */ 7647 component4 objname; 7648 createtype4 objtype; 7649 }; 7651 struct CREATE4resok { 7652 change_info4 cinfo; 7653 }; 7655 union CREATE4res switch (nfsstat4 status) { 7656 case NFS4_OK: 7657 CREATE4resok resok4; 7658 default: 7659 void; 7660 }; 7662 /* 7663 * DELEGPURGE: Purge Delegations Awaiting Recovery 7664 */ 7665 struct DELEGPURGE4args { 7666 clientid4 clientid; 7667 }; 7669 struct DELEGPURGE4res { 7670 nfsstat4 status; 7671 }; 7673 /* 7674 * DELEGRETURN: Return a delegation 7675 */ 7676 struct DELEGRETURN4args { 7677 stateid4 stateid; 7678 }; 7680 struct DELEGRETURN4res { 7681 nfsstat4 status; 7682 }; 7684 /* 7685 * GETATTR: Get file attributes 7686 */ 7687 struct GETATTR4args { 7688 /* CURRENT_FH: directory or file */ 7689 bitmap4 attr_request; 7690 }; 7692 struct GETATTR4resok { 7694 Draft Protocol Specification NFS version 4 October 1999 7696 fattr4 obj_attributes; 7697 }; 7699 union GETATTR4res switch (nfsstat4 status) { 7700 case NFS4_OK: 7701 GETATTR4resok resok4; 7702 default: 7703 void; 7704 }; 7706 /* 7707 * GETFH: Get current filehandle 7708 */ 7709 struct GETFH4resok { 7710 nfs_fh4 object; 7711 }; 7713 union GETFH4res switch (nfsstat4 status) { 7714 case NFS4_OK: 7715 GETFH4resok resok4; 7716 default: 7717 void; 7718 }; 7720 /* 7721 * LINK: Create link to an object 7722 */ 7723 struct LINK4args { 7724 /* CURRENT_FH: file */ 7725 nfs_fh4 dir; 7726 component4 newname; 7727 }; 7729 struct LINK4resok { 7730 change_info4 cinfo; 7731 }; 7733 union LINK4res switch (nfsstat4 status) { 7734 case NFS4_OK: 7735 LINK4resok resok4; 7736 default: 7737 void; 7738 }; 7740 /* 7741 * LOCK/LOCKT/LOCKU: Record lock management 7742 */ 7743 struct LOCK4args { 7745 Draft Protocol Specification NFS version 4 October 1999 7747 /* CURRENT_FH: file */ 7748 nfs_lock_type4 type; 7749 seqid4 seqid; 7750 bool reclaim; 7751 stateid4 stateid; 7752 offset4 offset; 7753 length4 length; 7754 }; 7756 struct lockres4 { 7757 stateid4 stateid; 7758 int32_t access; 7759 }; 7761 union LOCK4res switch (nfsstat4 status) { 7762 case NFS4_OK: 7763 lockres4 result; 7764 default: 7765 void; 7766 }; 7768 union LOCKT4res switch (nfsstat4 status) { 7769 case NFS4ERR_DENIED: 7770 nfs_lockowner4 owner; 7771 case NFS4_OK: 7772 void; 7773 default: 7774 void; 7775 }; 7777 union LOCKU4res switch (nfsstat4 status) { 7778 case NFS4_OK: 7779 stateid4 stateid_ok; 7780 default: 7781 stateid4 stateid_oth; 7782 }; 7784 /* 7785 * LOOKUP: Lookup filename 7786 */ 7787 struct LOOKUP4args { 7788 /* CURRENT_FH: directory */ 7789 pathname4 path; 7790 }; 7792 struct LOOKUP4res { 7793 /* CURRENT_FH: object */ 7794 nfsstat4 status; 7796 Draft Protocol Specification NFS version 4 October 1999 7798 }; 7800 /* 7801 * LOOKUPP: Lookup parent directory 7802 */ 7803 struct LOOKUPP4res { 7804 /* CURRENT_FH: directory */ 7805 nfsstat4 status; 7806 }; 7808 /* 7809 * NVERIFY: Verify attributes different 7810 */ 7811 struct NVERIFY4args { 7812 /* CURRENT_FH: object */ 7813 bitmap4 attr_request; 7814 fattr4 obj_attributes; 7815 }; 7817 struct NVERIFY4res { 7818 nfsstat4 status; 7819 }; 7821 /* 7822 * Various definitions for OPEN 7823 */ 7824 enum createmode4 { 7825 UNCHECKED4 = 0, 7826 GUARDED4 = 1, 7827 EXCLUSIVE4 = 2 7828 }; 7830 union createhow4 switch (createmode4 mode) { 7831 case UNCHECKED4: 7832 case GUARDED4: 7833 fattr4 createattrs; 7834 case EXCLUSIVE4: 7835 createverf4 verf; 7836 }; 7838 enum opentype4 { 7839 OPEN4_NOCREATE = 0, 7840 OPEN4_CREATE = 1 7841 }; 7843 union openflag4 switch (opentype4 opentype) { 7844 case OPEN4_CREATE: 7845 createhow4 how; 7847 Draft Protocol Specification NFS version 4 October 1999 7849 default: 7850 void; 7851 }; 7853 enum limit_by4 { 7854 NFS_LIMIT_SIZE = 1, 7855 NFS_LIMIT_BLOCKS = 2 /* experimental; 7856 subject to change*/ 7857 /* others as needed */ 7858 }; 7860 struct nfs_modified_limit4 { 7861 uint64_t bytes; 7862 uint32_t blocksize; 7863 }; 7865 union nfs_space_limit4 switch (limit_by4 limitby) { 7866 case NFS_LIMIT_SIZE: 7867 uint64_t filesize; 7868 case NFS_LIMIT_BLOCKS: 7869 nfs_modified_limit4 mod_blocks; 7870 } ; 7872 /* 7873 * Access and Deny constants for open argument 7874 */ 7875 const OPEN4_ACCESS_READ = 0x0001; 7876 const OPEN4_ACCESS_WRITE= 0x0002; 7877 const OPEN4_ACCESS_BOTH = 0x0003; 7879 const OPEN4_DENY_NONE = 0x0000; 7880 const OPEN4_DENY_READ = 0x0001; 7881 const OPEN4_DENY_WRITE = 0x0002; 7882 const OPEN4_DENY_BOTH = 0x0003; 7884 enum open_delegation_type4 { 7885 OPEN_DELEGATE_NONE = 0, 7886 OPEN_DELEGATE_READ = 1, 7887 OPEN_DELEGATE_WRITE = 2 7888 }; 7890 enum open_claim_type4 { 7891 CLAIM_NULL = 0, 7892 CLAIM_PREVIOUS = 1, 7893 CLAIM_DELEGATE_CUR = 2, 7894 CLAIM_DELEGATE_PREV = 3 7895 }; 7897 Draft Protocol Specification NFS version 4 October 1999 7899 struct open_claim_delegate_cur4 { 7900 pathname4 file; 7901 stateid4 delegate_stateid; 7902 }; 7904 union open_claim4 switch (open_claim_type4 claim) { 7905 /* 7906 * No special rights to file. Ordinary OPEN of the specified file. 7907 */ 7908 case CLAIM_NULL: 7909 /* CURRENT_FH: directory */ 7910 pathname4 file; 7912 /* 7913 * Right to the file established by an open previous to server 7914 * reboot. File identified by filehandle obtained at that time 7915 * rather than by name. 7916 */ 7917 case CLAIM_PREVIOUS: 7918 /* CURRENT_FH: file being reclaimed */ 7919 int32_t delegate_type; 7921 /* 7922 * Right to file based on a delegation granted by the server. 7923 * File is specified by name. 7924 */ 7925 case CLAIM_DELEGATE_CUR: 7926 /* CURRENT_FH: directory */ 7927 open_claim_delegate_cur4 delegate_cur_info; 7929 /* Right to file based on a delegation granted to a previous boot 7930 * instance of the client. File is specified by name. 7931 */ 7932 case CLAIM_DELEGATE_PREV: 7933 /* CURRENT_FH: directory */ 7934 pathname4 file_delegate_prev; 7935 }; 7937 /* 7938 * OPEN: Open a file, potentially receiving an open delegation 7939 */ 7940 struct OPEN4args { 7941 open_claim4 claim; 7942 openflag4 openhow; 7943 nfs_lockowner4 owner; 7944 seqid4 seqid; 7945 int32_t access; 7946 int32_t deny; 7948 Draft Protocol Specification NFS version 4 October 1999 7950 }; 7952 /* 7953 * Result flags 7954 */ 7955 /* Mandatory locking is in effect for this file. */ 7956 const OPEN4_RESULT_MLOCK = 0x0001; 7958 struct open_read_delegation4 { 7959 stateid4 stateid; /* Stateid for delegation*/ 7960 bool recall; /* Pre-recalled flag for 7961 delegations obtained 7962 by reclaim 7963 (CLAIM_PREVIOUS) */ 7964 nfsace4 permissions; /* Defines users who don't 7965 need an ACCESS call to 7966 open for read */ 7967 }; 7969 struct open_write_delegation4 { 7970 stateid4 stateid; /* Stateid for delegation 7971 be flushed to the server 7972 on close. */ 7973 bool recall; /* Pre-recalled flag for 7974 delegations obtained 7975 by reclaim 7976 (CLAIM_PREVIOUS) */ 7977 nfs_space_limit4 space_limit; /* Defines condition that 7978 the client must check to 7979 determine whether the 7980 file needs to be flushed 7981 to the server on close. 7982 */ 7983 nfsace4 permissions; /* Defines users who don't 7984 need an ACCESS call as 7985 part of a delegated 7986 open. */ 7987 }; 7989 union open_delegation4 7990 switch (open_delegation_type4 delegation_type) { 7991 case OPEN_DELEGATE_NONE: 7992 void; 7993 case OPEN_DELEGATE_READ: 7994 open_read_delegation4 read; 7995 case OPEN_DELEGATE_WRITE: 7996 open_write_delegation4 write; 7997 }; 7999 Draft Protocol Specification NFS version 4 October 1999 8001 struct OPEN4resok { 8002 stateid4 stateid; /* Stateid for open */ 8003 uint32_t rflags; /* Result flags */ 8004 int32_t access; /* Access granted */ 8005 open_delegation4 delegation; /* Info on any open 8006 delegation */ 8007 }; 8009 union OPEN4res switch (nfsstat4 status) { 8010 case NFS4_OK: 8011 /* CURRENT_FH: opened file */ 8012 OPEN4resok result; 8013 default: 8014 void; 8015 }; 8017 /* 8018 * OPENATTR: open named attributes directory 8019 */ 8020 struct OPENATTR4res { 8021 /* CURRENT_FH: name attr directory*/ 8022 nfsstat4 status; 8023 }; 8025 /* 8026 * PUTFH: Set current filehandle 8027 */ 8028 struct PUTFH4args { 8029 nfs_fh4 object; 8030 }; 8032 struct PUTFH4res { 8033 /* CURRENT_FH: */ 8034 nfsstat4 status; 8035 }; 8037 /* 8038 * PUTPUBFH: Set public filehandle 8039 */ 8040 struct PUTPUBFH4res { 8041 /* CURRENT_FH: public fh */ 8042 nfsstat4 status; 8043 }; 8045 /* 8046 * PUTROOTFH: Set root filehandle 8047 */ 8048 struct PUTROOTFH4res { 8050 Draft Protocol Specification NFS version 4 October 1999 8052 /* CURRENT_FH: root fh */ 8053 nfsstat4 status; 8054 }; 8056 /* 8057 * READ: Read from file 8058 */ 8059 struct READ4args { 8060 /* CURRENT_FH: file */ 8061 stateid4 stateid; 8062 offset4 offset; 8063 count4 count; 8064 }; 8066 struct READ4resok { 8067 bool eof; 8068 opaque data<>; 8069 }; 8071 union READ4res switch (nfsstat4 status) { 8072 case NFS4_OK: 8073 READ4resok resok4; 8074 default: 8075 void; 8076 }; 8078 /* 8079 * READDIR: Read directory 8080 */ 8081 struct READDIR4args { 8082 /* CURRENT_FH: directory */ 8083 nfs_cookie4 cookie; 8084 count4 dircount; 8085 count4 maxcount; 8086 bitmap4 attr_request; 8088 }; 8090 struct entry4 { 8091 nfs_cookie4 cookie; 8092 component4 name; 8093 fattr4 attrs; 8094 entry4 *nextentry; 8095 }; 8097 struct dirlist4 { 8098 entry4 *entries; 8099 bool eof; 8101 Draft Protocol Specification NFS version 4 October 1999 8103 }; 8105 struct READDIR4resok { 8106 dirlist4 reply; 8107 }; 8109 union READDIR4res switch (nfsstat4 status) { 8110 case NFS4_OK: 8111 READDIR4resok resok4; 8112 default: 8113 void; 8114 }; 8116 /* 8117 * READLINK: Read symbolic link 8118 */ 8119 struct READLINK4resok { 8120 linktext4 link; 8121 }; 8123 union READLINK4res switch (nfsstat4 status) { 8124 case NFS4_OK: 8125 READLINK4resok resok4; 8126 default: 8127 void; 8128 }; 8130 /* 8131 * REMOVE: Remove filesystem object 8132 */ 8133 struct REMOVE4args { 8134 /* CURRENT_FH: directory */ 8135 component4 target; 8136 }; 8138 struct REMOVE4resok { 8139 change_info4 cinfo; 8140 }; 8142 union REMOVE4res switch (nfsstat4 status) { 8143 case NFS4_OK: 8144 REMOVE4resok resok4; 8145 default: 8146 void; 8147 }; 8149 Draft Protocol Specification NFS version 4 October 1999 8151 /* 8152 * RENAME: Rename directory entry 8153 */ 8154 struct RENAME4args { 8155 /* CURRENT_FH: source directory */ 8156 component4 oldname; 8157 nfs_fh4 newdir; 8158 component4 newname; 8159 }; 8161 struct RENAME4resok { 8162 change_info4 source_cinfo; 8163 change_info4 target_cinfo; 8164 }; 8166 union RENAME4res switch (nfsstat4 status) { 8167 case NFS4_OK: 8168 RENAME4resok resok4; 8169 default: 8170 void; 8171 }; 8173 /* 8174 * RENEW: Renew a Lease 8175 */ 8176 struct RENEW4args { 8177 stateid4 stateid; 8178 }; 8180 struct RENEW4res { 8181 nfsstat4 status; 8182 }; 8184 /* 8185 * RESTOREFH: Restore saved filehandle 8186 */ 8188 struct RESTOREFH4res { 8189 /* CURRENT_FH: value of saved fh */ 8190 nfsstat4 status; 8191 }; 8193 /* 8194 * SAVEFH: Save current filehandle 8195 */ 8196 struct SAVEFH4res { 8197 /* SAVED_FH: value of current fh */ 8198 nfsstat4 status; 8200 Draft Protocol Specification NFS version 4 October 1999 8202 }; 8204 /* 8205 * SECINFO: Obtain Available Security Mechanisms 8206 */ 8207 struct SECINFO4args { 8208 /* CURRENT_FH: */ 8209 component4 name; 8210 }; 8212 /* 8213 * From RFC 2203 8214 */ 8215 enum rpc_gss_svc_t { 8216 RPC_GSS_SVC_NONE = 1, 8217 RPC_GSS_SVC_INTEGRITY = 2, 8218 RPC_GSS_SVC_PRIVACY = 3 8219 }; 8221 struct rpcsec_gss_info { 8222 sec_oid4 oid; 8223 qop4 qop; 8224 rpc_gss_svc_t service; 8225 }; 8227 struct secinfo4 { 8228 unsigned int flavor; 8229 opaque flavor_info<>; /* null for AUTH_SYS, AUTH_NONE; 8230 contains rpcsec_gss_info for 8231 RPCSEC_GSS. */ 8232 }; 8234 typedef secinfo4 SECINFO4resok<>; 8236 union SECINFO4res switch (nfsstat4 status) { 8237 case NFS4_OK: 8238 SECINFO4resok resok4; 8239 default: 8240 void; 8241 }; 8243 /* 8244 * SETATTR: Set attributes 8245 */ 8246 struct SETATTR4args { 8247 /* CURRENT_FH: target object */ 8248 stateid4 stateid; 8249 fattr4 obj_attributes; 8251 Draft Protocol Specification NFS version 4 October 1999 8253 }; 8255 struct SETATTR4res { 8256 nfsstat4 status; 8257 bitmap4 attrsset; 8258 }; 8260 /* 8261 * SETCLIENTID 8262 */ 8263 struct SETCLIENTID4args { 8264 seqid4 seqid; 8265 nfs_client_id4 client; 8266 cb_client4 callback; 8267 }; 8269 union SETCLIENTID4res switch (nfsstat4 status) { 8270 case NFS4_OK: 8271 clientid4 clientid; 8272 case NFS4ERR_CLID_INUSE: 8273 clientaddr4 client_using; 8274 default: 8275 void; 8276 }; 8278 /* 8279 * VERIFY: Verify attributes same 8280 */ 8281 struct VERIFY4args { 8282 /* CURRENT_FH: object */ 8283 bitmap4 attr_request; 8284 fattr4 obj_attributes; 8285 }; 8287 struct VERIFY4res { 8288 nfsstat4 status; 8289 }; 8291 /* 8292 * WRITE: Write to file 8293 */ 8294 enum stable_how4 { 8295 UNSTABLE4 = 0, 8296 DATA_SYNC4 = 1, 8297 FILE_SYNC4 = 2 8298 }; 8300 struct WRITE4args { 8302 Draft Protocol Specification NFS version 4 October 1999 8304 /* CURRENT_FH: file */ 8305 stateid4 stateid; 8306 offset4 offset; 8307 stable_how4 stable; 8308 opaque data<>; 8309 }; 8311 struct WRITE4resok { 8312 count4 count; 8313 stable_how4 committed; 8314 writeverf4 verf; 8315 }; 8317 union WRITE4res switch (nfsstat4 status) { 8318 case NFS4_OK: 8319 WRITE4resok resok4; 8320 default: 8321 void; 8322 }; 8324 /* 8325 * Operation arrays 8326 */ 8328 enum nfs_opnum4 { 8329 OP_ACCESS = 2, 8330 OP_CLOSE = 3, 8331 OP_COMMIT = 4, 8332 OP_CREATE = 5, 8333 OP_DELEGPURGE = 6, 8334 OP_DELEGRETURN = 7, 8335 OP_GETATTR = 8, 8336 OP_GETFH = 9, 8337 OP_LINK = 10, 8338 OP_LOCK = 11, 8339 OP_LOCKT = 12, 8340 OP_LOCKU = 13, 8341 OP_LOOKUP = 14, 8342 OP_LOOKUPP = 15, 8343 OP_NVERIFY = 16, 8344 OP_OPEN = 17, 8345 OP_OPENATTR = 18, 8346 OP_PUTFH = 19, 8347 OP_PUTPUBFH = 20, 8348 OP_PUTROOTFH = 21, 8349 OP_READ = 22, 8350 OP_READDIR = 23, 8351 OP_READLINK = 24, 8353 Draft Protocol Specification NFS version 4 October 1999 8355 OP_REMOVE = 25, 8356 OP_RENAME = 26, 8357 OP_RENEW = 27, 8358 OP_RESTOREFH = 28, 8359 OP_SAVEFH = 29, 8360 OP_SECINFO = 30, 8361 OP_SETATTR = 31, 8362 OP_SETCLIENTID = 32, 8363 OP_VERIFY = 33, 8364 OP_WRITE = 34 8365 }; 8367 union nfs_argop4 switch (nfs_opnum4 argop) { 8368 case OP_ACCESS: ACCESS4args opaccess; 8369 case OP_CLOSE: CLOSE4args opclose; 8370 case OP_COMMIT: COMMIT4args opcommit; 8371 case OP_CREATE: CREATE4args opcreate; 8372 case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; 8373 case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; 8374 case OP_GETATTR: GETATTR4args opgetattr; 8375 case OP_GETFH: void; 8376 case OP_LINK: LINK4args oplink; 8377 case OP_LOCK: LOCK4args oplock; 8378 case OP_LOCKT: LOCK4args oplockt; 8379 case OP_LOCKU: LOCK4args oplocku; 8380 case OP_LOOKUP: LOOKUP4args oplookup; 8381 case OP_LOOKUPP: void; 8382 case OP_NVERIFY: NVERIFY4args opnverify; 8383 case OP_OPEN: OPEN4args opopen; 8384 case OP_OPENATTR: void; 8385 case OP_PUTFH: PUTFH4args opputfh; 8386 case OP_PUTPUBFH: void; 8387 case OP_PUTROOTFH: void; 8388 case OP_READ: READ4args opread; 8389 case OP_READDIR: READDIR4args opreaddir; 8390 case OP_READLINK: void; 8391 case OP_REMOVE: REMOVE4args opremove; 8392 case OP_RENAME: RENAME4args oprename; 8393 case OP_RENEW: RENEW4args oprenew; 8394 case OP_RESTOREFH: void; 8395 case OP_SAVEFH: void; 8396 case OP_SECINFO: SECINFO4args opsecinfo; 8397 case OP_SETATTR: SETATTR4args opsetattr; 8398 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 8399 case OP_VERIFY: VERIFY4args opverify; 8400 case OP_WRITE: WRITE4args opwrite; 8401 }; 8403 Draft Protocol Specification NFS version 4 October 1999 8405 union nfs_resop4 switch (nfs_opnum4 resop){ 8406 case OP_ACCESS: ACCESS4res opaccess; 8407 case OP_CLOSE: CLOSE4res opclose; 8408 case OP_COMMIT: COMMIT4res opcommit; 8409 case OP_CREATE: CREATE4res opcreate; 8410 case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; 8411 case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; 8412 case OP_GETATTR: GETATTR4res opgetattr; 8413 case OP_GETFH: GETFH4res opgetfh; 8414 case OP_LINK: LINK4res oplink; 8415 case OP_LOCK: LOCK4res oplock; 8416 case OP_LOCKT: LOCKT4res oplockt; 8417 case OP_LOCKU: LOCKU4res oplocku; 8418 case OP_LOOKUP: LOOKUP4res oplookup; 8419 case OP_LOOKUPP: LOOKUPP4res oplookupp; 8420 case OP_NVERIFY: NVERIFY4res opnverify; 8421 case OP_OPEN: OPEN4res opopen; 8422 case OP_OPENATTR: OPENATTR4res opopenattr; 8423 case OP_PUTFH: PUTFH4res opputfh; 8424 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 8425 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 8426 case OP_READ: READ4res opread; 8427 case OP_READDIR: READDIR4res opreaddir; 8428 case OP_READLINK: READLINK4res opreadlink; 8429 case OP_REMOVE: REMOVE4res opremove; 8430 case OP_RENAME: RENAME4res oprename; 8431 case OP_RENEW: RENEW4res oprenew; 8432 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 8433 case OP_SAVEFH: SAVEFH4res opsavefh; 8434 case OP_SECINFO: SECINFO4res opsecinfo; 8435 case OP_SETATTR: SETATTR4res opsetattr; 8436 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 8437 case OP_VERIFY: VERIFY4res opverify; 8438 case OP_WRITE: WRITE4res opwrite; 8439 }; 8441 struct COMPOUND4args { 8442 utf8string tag; 8443 nfs_argop4 argarray<>; 8444 }; 8446 struct COMPOUND4res { 8447 nfsstat4 status; 8448 utf8string tag; 8449 nfs_resop4 resarray<>; 8450 }; 8452 /* 8454 Draft Protocol Specification NFS version 4 October 1999 8456 * Remote file service routines 8457 */ 8458 program NFS4_PROGRAM { 8459 version NFS_V4 { 8460 void 8461 NFSPROC4_NULL(void) = 0; 8463 COMPOUND4res 8464 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 8466 } = 4; 8467 } = 100003; 8469 /* 8470 * NFS4 Callback Procedure Definitions and Program 8471 */ 8473 /* 8474 * CB_GETATTR: Get Current Attributes 8475 */ 8476 struct CB_GETATTR4args { 8477 nfs_fh4 fh; 8478 bitmap4 attr_request; 8479 }; 8481 struct CB_GETATTR4resok { 8482 fattr4 obj_attributes; 8483 }; 8485 union CB_GETATTR4res switch (nfsstat4 status) { 8486 case NFS4_OK: 8487 CB_GETATTR4resok resok4; 8488 default: 8489 void; 8490 }; 8492 /* 8493 * CB_RECALL: Recall an Open Delegation 8494 */ 8495 struct CB_RECALL4args { 8496 stateid4 stateid; 8497 bool truncate; 8498 nfs_fh4 fh; 8499 }; 8501 struct CB_RECALL4res { 8503 Draft Protocol Specification NFS version 4 October 1999 8505 nfsstat4 status; 8506 }; 8508 /* 8509 * Various definitions for CB_COMPOUND 8510 */ 8511 enum nfs_cb_opnum4 { 8512 OP_CB_GETATTR = 2, 8513 OP_CB_RECALL = 3 8514 }; 8516 union nfs_cb_argop4 switch (unsigned argop) { 8517 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 8518 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 8519 }; 8521 union nfs_cb_resop4 switch (unsigned resop){ 8522 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 8523 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 8524 }; 8526 struct CB_COMPOUND4args { 8527 utf8string tag; 8528 nfs_cb_argop4 argarray<>; 8529 }; 8531 struct CB_COMPOUND4res { 8532 nfsstat4 status; 8533 utf8string tag; 8534 nfs_cb_resop4 resarray<>; 8535 }; 8537 /* 8538 * Program number is in the transient range since the client 8539 * will assign the exact transient program number and provide 8540 * that to the server via the SETCLIENTID operation. 8541 */ 8542 program NFS4_CALLBACK { 8543 version NFS_CB { 8544 void 8545 CB_NULL(void) = 0; 8546 CB_COMPOUND4res 8547 CB_COMPOUND(CB_COMPOUND4args) = 1; 8548 } = 1; 8549 } = 40000000; 8551 Draft Protocol Specification NFS version 4 October 1999 8553 18. Bibliography 8555 [Gray] 8556 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 8557 for Distributed File Cache Consistency," Proceedings of the Twelfth 8558 Symposium on Operating Systems Principles, p. 202-210, December 1989. 8560 [Juszczak] 8561 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 8562 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 8563 CA, June 1990, pages 53-63. Describes reply cache implementation 8564 that avoids work in the server by handling duplicate requests. More 8565 important, though listed as a side-effect, the reply cache aids in 8566 the avoidance of destructive non-idempotent operation re-application 8567 -- improving correctness. 8569 [Kazar] 8570 Kazar, Michael Leon, "Synchronization and Caching Issues in the 8571 Andrew File System," USENIX Conference Proceedings, USENIX 8572 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 8573 description of the cache consistency scheme in AFS. Contrasted with 8574 other distributed file systems. 8576 [Macklem] 8577 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 8578 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 8579 Association, Berkeley, CA, January 1991. Describes performance work 8580 in tuning the 4.3BSD Reno NFS implementation. Describes performance 8581 improvement (reduced CPU loading) through elimination of data copies. 8583 [Mogul] 8584 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 8585 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 8586 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 8587 lease-based scheme for recovering state of consistency protocol. 8589 [Nowicki] 8590 Nowicki, Bill, "Transport Issues in the Network File System," ACM 8591 SIGCOMM newsletter Computer Communication Review, April 1989. A 8592 brief description of the basis for the dynamic retransmission work. 8594 Draft Protocol Specification NFS version 4 October 1999 8596 [Pawlowski] 8597 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 8598 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 8599 Conf. Proc., (1989) Description of an NFS server implementation for 8600 IBM's MVS operating system. 8602 [RFC1094] 8603 Sun Microsystems, Inc., "NFS: Network File System Protocol 8604 Specification", RFC1094, March 1989. 8606 http://www.ietf.org/rfc/rfc1094.txt 8608 [RFC1345] 8609 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 8610 Rationel Almen Planlaegning, June 1992. 8612 http://www.ietf.org/rfc/rfc1345.txt 8614 [RFC1813] 8615 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 8616 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 8618 http://www.ietf.org/rfc/rfc1813.txt 8620 [RFC1831] 8621 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 8622 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 8624 http://www.ietf.org/rfc/rfc1831.txt 8626 [RFC1832] 8627 Srinivasan, R., "XDR: External Data Representation Standard", 8628 RFC1832, Sun Microsystems, Inc., August 1995. 8630 http://www.ietf.org/rfc/rfc1832.txt 8632 [RFC1833] 8633 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 8634 Sun Microsystems, Inc., August 1995. 8636 http://www.ietf.org/rfc/rfc1833.txt 8638 Draft Protocol Specification NFS version 4 October 1999 8640 [RFC2054] 8641 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 8642 Microsystems, Inc., October 1996 8644 http://www.ietf.org/rfc/rfc2054.txt 8646 [RFC2055] 8647 Callaghan, B., "WebNFS Server Specification", RFC2054, Sun 8648 Microsystems, Inc., October 1996 8650 http://www.ietf.org/rfc/rfc2055.txt 8652 [RFC2078] 8653 Linn, J., "Generic Security Service Application Program Interface, 8654 Version 2", RFC2078, OpenVision Technologies, January 1997. 8656 http://www.ietf.org/rfc/rfc2078.txt 8658 [RFC2152] 8659 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 8660 RFC2152, Apple Computer, Inc., May 1997 8662 http://www.ietf.org/rfc/rfc2152.txt 8664 [RFC2203] 8665 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 8666 RFC2203, Sun Microsystems, Inc., August 1995. 8668 http://www.ietf.org/rfc/rfc2203.txt 8670 [RFC2279] 8671 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 8672 Alis Technologies, January 1998. 8674 http://www.ietf.org/rfc/rfc2279.txt 8676 [RFC2623] 8677 Eisler, M., "NFS Version 2 and Version 3 Security Issues and the NFS 8678 Protocol's Use of RPCSEC_GSS and Kerberos V5", RFC2623, Sun 8679 Microsystems, June 1999 8681 http://www.ietf.org/rfc/rfc2623.txt 8683 Draft Protocol Specification NFS version 4 October 1999 8685 [RFC2624] 8686 Shepler, S., "NFS Version 4 Design Considerations", RFC2624, Sun 8687 Microsystems, June 1999 8689 http://www.ietf.org/rfc/rfc2624.txt 8691 [Sandberg] 8692 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 8693 and Implementation of the Sun Network Filesystem," USENIX Conference 8694 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 8695 basic paper describing the SunOS implementation of the NFS version 2 8696 protocol, and discusses the goals, protocol specification and trade- 8697 offs. 8699 [Srinivasan] 8700 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 8701 Performance of Cache Consistency Protocols", WRL Research Report 8702 89/5, Digital Equipment Corporation Western Research Laboratory, 100 8703 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 8704 the effect of applying a Sprite-like consistency protocol applied to 8705 standard NFS. The issues of recovery in a stateful environment are 8706 covered in [Mogul]. 8708 [Unicode1] 8709 "Unicode Technical Report #8 - The Unicode Standard, Version 2.1", 8710 Unicode, Inc., The Unicode Consortium, P.O. Box 700519, San Jose, CA 8711 95710-0519 USA, September 1998 8713 http://www.unicode.org/unicode/reports/tr8.html 8715 [Unicode2] 8716 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 8717 700519, San Jose, CA 95710-0519 USA, October 1998 8719 http://www.unicode.org/unicode/standard/unsupported.html 8721 [XNFS] 8722 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 8723 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 8724 1-85912-184-5, February 1998. 8726 HTML version available: http://www.opengroup.org 8728 Draft Protocol Specification NFS version 4 October 1999 8730 19. Authors and Contributors 8732 General feedback related to this document should be directed to: 8734 nfsv4-wg@sunroof.eng.sun.com 8736 or the editor. 8738 19.1. Editor's Address 8740 Spencer Shepler 8741 Sun Microsystems, Inc. 8742 7808 Moonflower Drive 8743 Austin, Texas 78750 8745 Phone: +1 512-349-9376 8746 E-mail: shepler@eng.sun.com 8748 19.2. Authors' Addresses 8750 Carl Beame 8751 Hummingbird Communications Ltd. 8753 E-mail: beame@bws.com 8755 Brent Callaghan 8756 Sun Microsystems, Inc. 8757 901 San Antonio Road 8758 Palo Alto, CA 94303 8760 Phone: +1 650-786-5067 8761 E-mail: brent.callaghan@eng.sun.com 8763 Mike Eisler 8764 Sun Microsystems, Inc. 8765 5565 Wilson Road 8766 Colorado Springs, CO 80919 8768 Phone: +1 719-599-9026 8769 E-mail: mre@eng.sun.com 8771 Dave Noveck 8772 Network Appliance 8773 495 East Java Drive 8774 Sunnyvale, CA 94089 8776 Draft Protocol Specification NFS version 4 October 1999 8778 Phone: +1 781-861-9291 8779 E-mail: dave.noveck@netapp.com 8781 David Robinson 8782 Sun Microsystems, Inc. 8783 901 San Antonio Road 8784 Palo Alto, CA 94303 8786 Phone: +1 650-786-5088 8787 E-mail: david.robinson@eng.sun.com 8789 Robert Thurlow 8790 Sun Microsystems, Inc. 8791 901 San Antonio Road 8792 Palo Alto, CA 94303 8794 Phone: +1 650-786-5096 8795 E-mail: robert.thurlow@eng.sun.com 8797 Draft Protocol Specification NFS version 4 October 1999 8799 20. Full Copyright Statement 8801 "Copyright (C) The Internet Society (1999). All Rights Reserved. 8803 This document and translations of it may be copied and furnished to 8804 others, and derivative works that comment on or otherwise explain it 8805 or assist in its implementation may be prepared, copied, published 8806 and distributed, in whole or in part, without restriction of any 8807 kind, provided that the above copyright notice and this paragraph are 8808 included on all such copies and derivative works. However, this 8809 document itself may not be modified in any way, such as by removing 8810 the copyright notice or references to the Internet Society or other 8811 Internet organizations, except as needed for the purpose of 8812 developing Internet standards in which case the procedures for 8813 copyrights defined in the Internet Standards process must be 8814 followed, or as required to translate it into languages other than 8815 English. 8817 The limited permissions granted above are perpetual and will not be 8818 revoked by the Internet Society or its successors or assigns. 8820 This document and the information contained herein is provided on an 8821 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 8822 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 8823 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 8824 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 8825 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."