idnits 2.17.1 draft-ietf-nfsv4-03-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** 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 2 longer pages, the longest (page 32) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 230 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 513 has weird spacing: '...ned int uin...' == Line 517 has weird spacing: '...d hyper uint6...' == Line 581 has weird spacing: '...8string typ...' == Line 642 has weird spacing: '...8string ser...' == Line 710 has weird spacing: '...ned int cb_pr...' == (34 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 (December 1999) is 8899 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 9451 looks like a reference -- Missing reference section? 'RFC1813' on line 9469 looks like a reference -- Missing reference section? 'RFC1831' on line 9475 looks like a reference -- Missing reference section? 'RFC1832' on line 9481 looks like a reference -- Missing reference section? 'RFC2623' on line 9539 looks like a reference -- Missing reference section? 'RFC1964' on line 794 looks like a reference -- Missing reference section? 'RFCXXXX' on line 863 looks like a reference -- Missing reference section? '8' on line 537 looks like a reference -- Missing reference section? '4' on line 8331 looks like a reference -- Missing reference section? 'RFC2203' on line 9525 looks like a reference -- Missing reference section? 'RFC1700' on line 9463 looks like a reference -- Missing reference section? 'RFC1833' on line 9489 looks like a reference -- Missing reference section? 'RFC2581' on line 760 looks like a reference -- Missing reference section? 'RFC2078' on line 9513 looks like a reference -- Missing reference section? 'RFC2025' on line 9495 looks like a reference -- Missing reference section? 'RFC2054' on line 9501 looks like a reference -- Missing reference section? 'RFC2055' on line 9507 looks like a reference -- Missing reference section? 'RFC2624' on line 9546 looks like a reference -- Missing reference section? 'XNFS' on line 9584 looks like a reference -- Missing reference section? 'RFC1345' on line 9457 looks like a reference -- Missing reference section? 'RFC2279' on line 9533 looks like a reference -- Missing reference section? 'RFC2152' on line 9519 looks like a reference -- Missing reference section? 'Unicode1' on line 9569 looks like a reference -- Missing reference section? 'Unicode2' on line 9578 looks like a reference -- Missing reference section? 'Gray' on line 9404 looks like a reference -- Missing reference section? 'Juszczak' on line 9409 looks like a reference -- Missing reference section? 'Kazar' on line 9418 looks like a reference -- Missing reference section? 'Macklem' on line 9425 looks like a reference -- Missing reference section? 'Mogul' on line 9567 looks like a reference -- Missing reference section? 'Nowicki' on line 9438 looks like a reference -- Missing reference section? 'Pawlowski' on line 9445 looks like a reference -- Missing reference section? 'Sandberg' on line 9552 looks like a reference -- Missing reference section? 'Srinivasan' on line 9560 looks like a reference Summary: 4 errors (**), 0 flaws (~~), 10 warnings (==), 36 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 Sun Microsystems 3 Document: draft-ietf-nfsv4-03-00.txt C. Beame 4 Hummingbird Communications 5 B. Callaghan 6 Sun Microsystems 7 M. Eisler 8 Sun Microsystems 9 D. Noveck 10 Network Appliance 11 D. Robinson 12 Sun Microsystems 13 R. Thurlow 14 Sun Microsystems 15 December 1999 17 NFS version 4 Protocol 19 Status of this Memo 21 This document is an Internet-Draft and is in full conformance with 22 all provisions of Section 10 of RFC2026. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet- Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 Abstract 42 NFS version 4 is a distributed file system protocol which owes 43 heritage to NFS versions 2 [RFC1094] and 3 [RFC1813]. Unlike earlier 45 Draft Specification NFS version 4 Protocol December 1999 47 versions, NFS version 4 supports traditional file access while 48 integrating support for file locking and the mount protocol. In 49 addition, support for strong security (and its negotiation), compound 50 operations, and internationalization have been added. Of course, 51 attention has been applied to making NFS version 4 operate well in an 52 Internet environment. 54 Copyright 56 Copyright (C) The Internet Society (1999). All Rights Reserved. 58 Key Words 60 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 61 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 62 document are to be interpreted as described in RFC 2119. 64 Draft Specification NFS version 4 Protocol December 1999 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 69 1.1. Overview of NFS Version 4 Features . . . . . . . . . . . . 7 70 1.1.1. RPC and Security . . . . . . . . . . . . . . . . . . . . 8 71 1.1.2. Procedure and Operation Structure . . . . . . . . . . . 8 72 1.1.3. File System Model . . . . . . . . . . . . . . . . . . . 9 73 1.1.3.1. Filehandle Types . . . . . . . . . . . . . . . . . . . 9 74 1.1.3.2. Attribute Types . . . . . . . . . . . . . . . . . . 10 75 1.1.3.3. File System Replication and Migration . . . . . . . 10 76 1.1.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . . 11 77 1.1.5. File locking . . . . . . . . . . . . . . . . . . . . . 11 78 1.1.6. Client Caching and Delegation . . . . . . . . . . . . 11 79 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . 13 80 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 13 81 2.2. Structured Data Types . . . . . . . . . . . . . . . . . 14 82 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . 18 83 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 18 84 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 18 85 3.2.1. Security mechanisms for NFS version 4 . . . . . . . . 18 86 3.2.1.1. Kerberos V5 as security triple . . . . . . . . . . . 19 87 3.2.1.2. LIPKEY as a security triple . . . . . . . . . . . . 19 88 3.2.1.3. SPKM-3 as a security triple . . . . . . . . . . . . 20 89 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 21 90 3.3.1. Security Error . . . . . . . . . . . . . . . . . . . . 21 91 3.3.2. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 21 92 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . 22 93 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 22 94 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . . 22 95 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . . 23 96 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 23 97 4.2.1. General Properties of a Filehandle . . . . . . . . . . 24 98 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . . 24 99 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 25 100 4.2.4. One Method of Constructing a Volatile Filehandle . . . 26 101 4.3. Client Recovery from Filehandle Expiration . . . . . . . 26 102 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 28 103 5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 29 104 5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 29 105 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 29 106 5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 31 107 5.5. Recommended Attributes - Definitions . . . . . . . . . . 34 108 5.6. Interpreting owner and owner_group . . . . . . . . . . . 39 109 5.7. Quota Attributes . . . . . . . . . . . . . . . . . . . . 40 110 5.8. Access Control Lists . . . . . . . . . . . . . . . . . . 41 111 5.8.1. ACE type . . . . . . . . . . . . . . . . . . . . . . . 42 112 5.8.2. ACE flag . . . . . . . . . . . . . . . . . . . . . . . 42 113 5.8.3. ACE Access Mask . . . . . . . . . . . . . . . . . . . 43 115 Draft Specification NFS version 4 Protocol December 1999 117 5.8.4. ACE who . . . . . . . . . . . . . . . . . . . . . . . 44 118 6. File System Migration and Replication . . . . . . . . . . 46 119 6.1. Replication . . . . . . . . . . . . . . . . . . . . . . 46 120 6.2. Migration . . . . . . . . . . . . . . . . . . . . . . . 46 121 6.3. Interpretation of the fs_locations Attribute . . . . . . 47 122 6.4. Filehandle Recovery for Migration or Replication . . . . 48 123 7. NFS Server Namespace . . . . . . . . . . . . . . . . . . . 49 124 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 49 125 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 49 126 7.3. Server Pseudo File System . . . . . . . . . . . . . . . 50 127 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 50 128 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 50 129 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 51 130 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 51 131 7.8. Security Policy and Namespace Presentation . . . . . . . 51 132 8. File Locking . . . . . . . . . . . . . . . . . . . . . . . 53 133 8.1. Definitions . . . . . . . . . . . . . . . . . . . . . . 53 134 8.2. Locking . . . . . . . . . . . . . . . . . . . . . . . . 54 135 8.2.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 54 136 8.2.2. nfs_lockowner and stateid Definition . . . . . . . . . 56 137 8.2.3. Use of the stateid . . . . . . . . . . . . . . . . . . 58 138 8.2.4. Sequencing of Lock Requests . . . . . . . . . . . . . 58 139 8.3. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 59 140 8.4. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 59 141 8.5. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 60 142 8.5.1. Client Failure and Recovery . . . . . . . . . . . . . 60 143 8.5.2. Server Failure and Recovery . . . . . . . . . . . . . 61 144 8.5.3. Network Partitions and Recovery . . . . . . . . . . . 63 145 8.6. Server Revocation of Locks . . . . . . . . . . . . . . . 64 146 8.7. Share Reservations . . . . . . . . . . . . . . . . . . . 65 147 8.8. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 65 148 8.9. Short and Long Leases . . . . . . . . . . . . . . . . . 66 149 8.10. Clocks and Calculating Lease Expiration . . . . . . . . 66 150 9. Client-Side Caching . . . . . . . . . . . . . . . . . . . 68 151 9.1. Performance Challenges for Client-Side Caching . . . . . 68 152 9.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 69 153 9.2.1. Delegation Recovery . . . . . . . . . . . . . . . . . 71 154 9.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 72 155 9.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . . 73 156 9.3.2. Data Caching and File Locking . . . . . . . . . . . . 73 157 9.3.3. Data Caching and Mandatory File Locking . . . . . . . 75 158 9.3.4. Data Caching and File Identity . . . . . . . . . . . . 75 159 9.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 77 160 9.4.1. Open Delegation and Data Caching . . . . . . . . . . . 79 161 9.4.2. Open Delegation and File Locks . . . . . . . . . . . . 80 162 9.4.3. Recall of Open Delegation . . . . . . . . . . . . . . 80 163 9.4.4. Delegation Revocation . . . . . . . . . . . . . . . . 82 164 9.5. Data Caching and Revocation . . . . . . . . . . . . . . 83 166 Draft Specification NFS version 4 Protocol December 1999 168 9.5.1. Revocation Recovery for Write Open Delegation . . . . 83 169 9.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 84 170 9.7. Name Caching . . . . . . . . . . . . . . . . . . . . . . 85 171 9.8. Directory Caching . . . . . . . . . . . . . . . . . . . 86 172 10. Minor Versioning . . . . . . . . . . . . . . . . . . . . 88 173 11. Internationalization . . . . . . . . . . . . . . . . . . 91 174 11.1. Universal Versus Local Character Sets . . . . . . . . . 91 175 11.2. Overview of Universal Character Set Standards . . . . . 92 176 11.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 93 177 11.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 94 178 12. Error Definitions . . . . . . . . . . . . . . . . . . . . 95 179 13. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 100 180 13.1. Compound Procedure . . . . . . . . . . . . . . . . . . 100 181 13.2. Evaluation of a Compound Request . . . . . . . . . . . 101 182 13.3. Operation Values . . . . . . . . . . . . . . . . . . . 101 183 14. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 102 184 14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 102 185 14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 103 186 14.2.1. Operation 3: ACCESS - Check Access Rights . . . . . . 106 187 14.2.2. Operation 4: CLOSE - Close File . . . . . . . . . . . 109 188 14.2.3. Operation 5: COMMIT - Commit Cached Data . . . . . . 111 189 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 114 190 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 191 Recovery . . . . . . . . . . . . . . . . . . . . . . 116 192 14.2.6. Operation 8: DELEGRETURN - Return Delegation . . . . 117 193 14.2.7. Operation 9: GETATTR - Get Attributes . . . . . . . . 118 194 14.2.8. Operation 10: GETFH - Get Current Filehandle . . . . 120 195 14.2.9. Operation 11: LINK - Create Link to a File . . . . . 122 196 14.2.10. Operation 12: LOCK - Create Lock . . . . . . . . . . 124 197 14.2.11. Operation 13: LOCKT - Test For Lock . . . . . . . . 126 198 14.2.12. Operation 14: LOCKU - Unlock File . . . . . . . . . 128 199 14.2.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . 130 200 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory . . 133 201 14.2.15. Operation 17: NVERIFY - Verify Difference in 202 Attributes . . . . . . . . . . . . . . . . . . . . . 135 203 14.2.16. Operation 18: OPEN - Open a Regular File . . . . . . 137 204 14.2.17. Operation 19: OPENATTR - Open Named Attribute 205 Directory . . . . . . . . . . . . . . . . . . . . . 145 206 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . 147 207 14.2.19. Operation 21: PUTFH - Set Current Filehandle . . . . 149 208 14.2.20. Operation 22: PUTPUBFH - Set Public Filehandle . . . 150 209 14.2.21. Operation 23: PUTROOTFH - Set Root Filehandle . . . 151 210 14.2.22. Operation 24: READ - Read from File . . . . . . . . 152 211 14.2.23. Operation 25: READDIR - Read Directory . . . . . . . 154 212 14.2.24. Operation 26: READLINK - Read Symbolic Link . . . . 158 213 14.2.25. Operation 27: REMOVE - Remove Filesystem Object . . 160 214 14.2.26. Operation 28: RENAME - Rename Directory Entry . . . 162 215 14.2.27. Operation 29: RENEW - Renew a Lease . . . . . . . . 165 217 Draft Specification NFS version 4 Protocol December 1999 219 14.2.28. Operation 30: RESTOREFH - Restore Saved Filehandle . 167 220 14.2.29. Operation 31: SAVEFH - Save Current Filehandle . . . 169 221 14.2.30. Operation 32: SECINFO - Obtain Available Security . 170 222 14.2.31. Operation 33: SETATTR - Set Attributes . . . . . . . 172 223 14.2.32. Operation 34: SETCLIENTID - Negotiate Clientid . . . 174 224 14.2.33. Operation 35: SETCLIENTID_CONFIRM - Confirm Clientid 176 225 14.2.34. Operation 36: VERIFY - Verify Same Attributes . . . 178 226 14.2.35. Operation 37: WRITE - Write to File . . . . . . . . 180 227 15. NFS Version 4 Callback Procedures . . . . . . . . . . . . 185 228 15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 185 229 15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 186 230 15.2.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . 188 231 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation . 190 232 16. Security Considerations . . . . . . . . . . . . . . . . . 191 233 17. RPC definition file . . . . . . . . . . . . . . . . . . . 192 234 18. Bibliography . . . . . . . . . . . . . . . . . . . . . . 223 235 19. Authors and Contributors . . . . . . . . . . . . . . . . 228 236 19.1. Editor's Address . . . . . . . . . . . . . . . . . . . 228 237 19.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 228 238 20. Full Copyright Statement . . . . . . . . . . . . . . . . 230 240 Draft Specification NFS version 4 Protocol December 1999 242 1. Introduction 244 The NFS version 4 protocol is a further revision of the NFS protocol 245 defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains 246 the essential characteristics of previous versions: design for easy 247 recovery, independent of transport protocols, operating systems and 248 filesystems, simplicity, and good performance. The NFS version 4 249 revision has the following goals: 251 o Improved access and good performance on the Internet. 253 The protocol is designed to transit firewalls easily, perform 254 well where latency is high and bandwidth is low, and scale to 255 very large numbers of clients per server. 257 o Strong security with negotiation built into the protocol. 259 The protocol builds on the work of the ONCRPC working group in 260 supporting the RPCSEC_GSS protocol. Additionally, the NFS 261 version 4 protocol provides a mechanism to allow clients and 262 servers the ability to negotiate security and require clients 263 and servers to support a minimal set of security schemes. 265 o Good cross-platform interoperability. 267 The protocol features a file system model that provides a 268 useful, common set of features that does not unduly favor one 269 file system or operating system over another. 271 o Designed for protocol extensions. 273 The protocol is designed to accept standard extensions that do 274 not compromise backward compatibility. 276 1.1. Overview of NFS Version 4 Features 278 To provide a reasonable context for the reader, the major features of 279 NFS version 4 protocol will be reviewed in brief. This will be done 280 to provide an appropriate context for both the reader who is familiar 281 with the previous versions of the NFS protocol and the reader that is 282 new to the NFS protocols. For the reader new to the NFS protocols, 283 there is still a fundamental knowledge that is expected. The reader 284 should be familiar with the XDR and RPC protocols as described in 286 Draft Specification NFS version 4 Protocol December 1999 288 [RFC1831] and [RFC1832]. A basic knowledge of file systems and 289 distributed file systems is expected as well. 291 1.1.1. RPC and Security 293 As with previous versions of NFS, the External Data Representation 294 (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS 295 version 4 protocol are those defined in [RFC1831] and [RFC1832]. To 296 meet end to end security requirements, the RPCSEC_GSS framework 297 [RFC2623] will be used to extend the basic RPC security. With the 298 use of RPCSEC_GSS, various mechanisms can be provided to offer 299 authentication, integrity, and privacy to the NFS version 4 protocol. 300 Kerberos V5 will be used as described in [RFC1964] to provide one 301 security framework. The LIPKEY GSS-API mechanism described in 302 [RFCXXXX] will be used to deliver the use of password and server 303 public key to the NFS version 4 protocol. With the use of 304 RPCSEC_GSS, other mechanisms may also be specified and used for NFS 305 version 4 security. 307 To enable in-band security negotiation, the NFS version 4 protocol 308 has added a new operation which provides the client a method of 309 querying the server about its policies regarding which security 310 mechanisms must be used for access to the server's file system 311 resources. With this, the client can securely match the security 312 mechanism that meets the policies specified at both the client and 313 server. 315 1.1.2. Procedure and Operation Structure 317 A significant departure from the previous versions of the NFS 318 protocol is the introduction of the COMPOUND procedure. For the NFS 319 version 4 protocol, there are two RPC procedures, NULL and COMPOUND. 320 The COMPOUND procedure is defined in terms of operations and these 321 operations correspond more closely to the traditional NFS procedures. 322 With the use of the COMPOUND procedure, the client is able to build 323 simple or complex requests. These COMPOUND requests allow for a 324 reduction in the number of RPCs needed for logical file system 325 operations. For example, without previous contact with a server a 326 client will be able to read data from a file in one request by 327 combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. 328 With previous versions of the NFS protocol, this type of single 329 request was not possible. 331 The model used for COMPOUND is very simple. There is no logical OR 332 or ANDing of operations. The operations combined within a COMPOUND 333 request are evaluated in order by the server. Once an operation 335 Draft Specification NFS version 4 Protocol December 1999 337 returns a failing result, the evaluation ends and the results of all 338 evaluated operations are returned to the client. 340 The NFS version 4 protocol has held onto the model of having the 341 client refer to a file or directory at the server by a "filehandle". 342 The COMPOUND procedure has a method of passing a filehandle from one 343 operation to another within the sequence of operations. There is a 344 concept of a "current filehandle" and "saved filehandle". Most 345 operations use the "current filehandle" as the file system object to 346 operate upon. The "saved filehandle" is used as temporary filehandle 347 storage within a COMPOUND procedure. 349 1.1.3. File System Model 351 The general file system model used for the NFS version 4 protocol is 352 the same as previous versions. The server file system is 353 hierarchical with the regular files contained within being treated as 354 opaque byte streams. In a slight departure, file and directory names 355 are encoded with UTF-8 to deal with the basics of 356 internationalization. 358 The NFS version 4 protocol does not require a separate protocol to 359 provide for the initial mapping between path name and filehandle. 360 Instead of using the older MOUNT protocol for this mapping, the 361 server provides a ROOT filehandle that represents the logical root or 362 top of the file system tree provided by the server. The server 363 provides multiple file systems by glueing them together with pseudo 364 file systems. These pseudo file systems provide for potential gaps 365 in the path names between real file systems. 367 1.1.3.1. Filehandle Types 369 In previous versions of the NFS protocol, the filehandle provided by 370 the server was guaranteed to be valid or persistent for the lifetime 371 of the file system object to which it referred. For some server 372 implementations, this persistence requirement has been difficult to 373 meet. For the NFS version 4 protocol, this requirement has been 374 relaxed by introducing another type of filehandle, volatile. With 375 persistent and volatile filehandle types, the server implementation 376 can match the abilities of the file system at the server along with 377 the operating environment. The client will have knowledge of the 378 type of filehandle being provided by the server and can be prepared 379 to deal with the semantics of each. 381 Draft Specification NFS version 4 Protocol December 1999 383 1.1.3.2. Attribute Types 385 The NFS version 4 protocol introduces three classes of file system or 386 file attributes. Like the additional filehandle type, the 387 classification of file attributes has been done to ease server 388 implementations along with extending the overall functionality of the 389 NFS protocol. This attribute model is structured to be extensible 390 such that new attributes can be introduced in minor revisions of the 391 protocol without requiring significant rework. 393 The three classifications are: mandatory, recommended and named 394 attributes. This is a significant departure from the previous 395 attribute model used in the NFS protocol. Previously, the attributes 396 for the file system and file objects were a fixed set of mainly Unix 397 attributes. If the server or client did not support a particular 398 attribute, it would have to simulate the attribute the best it could. 400 Mandatory attributes are the minimal set of file or file system 401 attributes that must be provided by the server and must be properly 402 represented by the server. Recommended attributes represent 403 different file system types and operating environments. The 404 recommended attributes will allow for better interoperability and the 405 inclusion of more operating environments. The mandatory and 406 recommended attribute sets are traditional file or file system 407 attributes. The third type of attribute is the named attribute. A 408 named attribute is an opaque byte stream that is associated with a 409 directory or file and referred to by a string name. Named attributes 410 are meant to be used by client applications as a method to associate 411 application specific data with a regular file or directory. 413 One significant addition to the recommended set of file attributes is 414 the Access Control List (ACL) attribute. This attribute provides for 415 directory and file access control beyond the model used in previous 416 versions of the NFS protocol. The ACL definition allows for 417 specification of user and group level access control. 419 1.1.3.3. File System Replication and Migration 421 With the use of a special file attribute, the ability to migrate or 422 replicate server file systems is enabled within the protocol. The 423 file system locations attribute provides a method for the client to 424 probe the server about the location of a file system. In the event 425 of a migration of a file system, the client will receive and error 426 when operating on the file system and it can then query as to the new 427 file system location. Similar steps are used for replication, the 428 client is able to query the server for the multiple available 429 locations of a particular file system. From this information, the 431 Draft Specification NFS version 4 Protocol December 1999 433 client can use its own policies to access the appropriate file system 434 location. 436 1.1.4. OPEN and CLOSE 438 The NFS version 4 protocol introduces OPEN and CLOSE operations. The 439 OPEN operation provides a single point where file lookup, creation, 440 and share semantics can be combined. The CLOSE operation also 441 provides for the release of state accumulated by OPEN. 443 1.1.5. File locking 445 With the NFS version 4 protocol, the support for byte range file 446 locking is part of the NFS protocol. The file locking support is 447 structured so that an RPC callback mechanism is not required. This 448 is a departure from the previous versions of the NFS file locking 449 protocol -- NLM. The state associated with file locks is maintained 450 at the server under a lease based model. The server defines a single 451 lease period for all state held by a NFS client. If the client does 452 not renew its lease within the defined period, all state associated 453 with the client's lease may be released by the server. The client 454 may renew its lease with use of the RENEW operation or implicitly by 455 use of other operations (primarily READ). 457 1.1.6. Client Caching and Delegation 459 The file, attribute, and directory caching for the NFS version 4 460 protocol is similar to previous versions. Attributes and directory 461 information are cached for a duration determined by the client. At 462 the end of a predefined timeout, the client will query the server to 463 see if the related file system object has been updated. 465 For file data, the client checks its cache validity when the file is 466 open. A query is sent to the server to determine if the file has 467 been changed. Based on this information, the client determines if 468 the data cache for the file should kept or release. Also, when the 469 file is closed, any modified data is written to the server. 471 If an application wants to serialize access to file data, file 472 locking of the file data ranges in question should be used. 474 The major addition to NFS version 4 in the area of caching is the 475 ability of the server to delegate certain responsibilities to the 476 client. When the server grants a delegation for a file to a client, 477 the client is guaranteed certain semantics with respect to the 479 Draft Specification NFS version 4 Protocol December 1999 481 sharing of that file with other clients. At OPEN, the client may ask 482 the server for either a read or write delegation for the file. If 483 the client is granted a read delegation, it is assured that no other 484 client has the ability to write to the file for the duration of the 485 delegation. If the client is granted a write delegation, the client 486 is assured that no other client has read or write access to the file. 488 Delegations can be recalled by the server. If another client 489 requests access to the file in such a way that the access conflicts 490 with the granted delegation, the server is able to notify the initial 491 client and recall the delegation. This requires that a callback path 492 exist between the server and client. If this callback path does not 493 exist, then delegations can not be granted. The essence of a 494 delegation is that it allows the client to locally service operations 495 such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate 496 interaction with the server. 498 Draft Specification NFS version 4 Protocol December 1999 500 2. Protocol Data Types 502 The syntax and semantics to describe the data types of the NFS 503 version 4 protocol are defined in the XDR [RFC1832] and RPC [RFC1831] 504 documents. The next sections build upon the XDR data types to define 505 types and structures specific to this protocol. 507 2.1. Basic Data Types 509 Data Type Definition 510 _____________________________________________________________________ 511 int32_t typedef int int32_t; 513 uint32_t typedef unsigned int uint32_t; 515 int64_t typedef hyper int64_t; 517 uint64_t typedef unsigned hyper uint64_t; 519 attrlist4 typedef opaque attrlist4<>; 520 Used for file/directory attributes 522 bitmap4 typedef uint32_t bitmap4<>; 523 Used in attribute array encoding. 525 clientid4 typedef uint64_t clientid4; 526 Shorthand reference to client identification 528 component4 typedef utf8string component4; 529 Represents path name components 531 cookieverf4 typedef opaque cookieverf4[8]; 532 Used for READDIR to verify cookie values 534 count4 typedef uint32_t count4; 535 Various count parameters (READ, WRITE, COMMIT) 537 createverf4 typedef opaque createverf4[8]; 538 Used for exclusive CREATE 540 length4 typedef uint64_t length4; 541 Describes LOCK lengths 543 linktext4 typedef utf8string linktext4; 544 Symbolic link contents 546 mode4 typedef uint32_t mode4; 547 Mode attribute data type 549 Draft Specification NFS version 4 Protocol December 1999 551 nfs_cookie4 typedef uint64_t nfs_cookie4; 552 Opaque cookie value for READDIR 554 nfs_fh4 typedef opaque nfs_fh4; 555 Filehandle definition; NFS4_FHSIZE is defined as 128 557 nfs_ftype4 enum nfs_ftype4; 558 Various defined file types 560 nfsstat4 enum nfsstat4; 561 Return value for operations 563 offset4 typedef uint64_t offset4; 564 Various offset designations (READ, WRITE, LOCK, COMMIT) 566 pathname4 typedef component4 pathname4<>; 567 Represents path name for LOOKUP, OPEN and others 569 qop4 typedef uint32_t qop4; 570 Quality of protection designation in SECINFO 572 sec_oid4 typedef opaque sec_oid4<>; 573 Security Object Identifier 575 seqid4 typedef uint32_t seqid4; 576 Sequence identifier used for file locking 578 stateid4 typedef uint64_t stateid4; 579 State identifier used for file locking and delegation 581 utf8string typedef opaque utf8string<>; 582 UTF-8 encoding for strings 584 writeverf4 typedef uint32_t writeverf4; 585 Write verifier used for WRITE and COMMIT 587 2.2. Structured Data Types 589 nfstime4 590 struct nfstime4 { 591 int64_t seconds; 592 uint32_t nseconds; 593 } 595 The nfstime4 structure gives the number of seconds and 597 Draft Specification NFS version 4 Protocol December 1999 599 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 600 Universal Time (UTC). Values greater than zero for the seconds 601 field denote dates after the 0 hour January 1, 1970. Values 602 less than zero for the seconds field denote dates before the 0 603 hour January 1, 1970. In both cases, the nseconds field is to 604 be added to the seconds field for the final time representation. 605 For example, if the time to be represented is one-half second 606 before 0 hour January 1, 1970, the seconds field would have a 607 value of negative one (-1) and the nseconds fields would have a 608 value of one-half second (500000000). Values greater than 609 999,999,999 for nseconds are considered invalid. 611 This data type is used to pass time and date information. A 612 server converts to and from local time when processing time 613 values, preserving as much accuracy as possible. If the 614 precision of timestamps stored for a file system object is less 615 than defined, loss of precision can occur. An adjunct time 616 maintenance protocol is recommended to reduce client and server 617 time skew. 619 specdata4 621 struct specdata4 { 622 uint32_t specdata1; 623 uint32_t specdata2; 624 } 626 This data type represents additional information for the device 627 file types NF4CHR and NF4BLK. 629 fsid4 631 struct fsid4 { 632 uint64_t major; 633 uint64_t minor; 634 }; 636 This type is the file system identifier that is used as a 637 mandatory attribute. 639 fs_location4 641 struct fs_location4 { 642 utf8string server<>; 643 pathname4 rootpath; 645 Draft Specification NFS version 4 Protocol December 1999 647 }; 649 fs_locations4 651 struct fs_locations4 { 652 pathname4 fs_root; 653 fs_location4 locations<>; 654 }; 656 The fs_location4 and fs_locations4 data types are used for the 657 fs_locations recommended attribute which is used for migration 658 and replication support. 660 fattr4 662 struct fattr4 { 663 bitmap4 attrmask; 664 attrlist4 attr_vals; 665 }; 667 The fattr4 structure is used to represent file and directory 668 attributes. 670 The bitmap is a counted array of 32 bit integers used to contain 671 bit values. The position of the integer in the array that 672 contains bit n can be computed from the expression (n / 32) and 673 its bit within that integer is (n mod 32). 675 0 1 676 +-----------+-----------+-----------+-- 677 | count | 31 .. 0 | 63 .. 32 | 678 +-----------+-----------+-----------+-- 680 change_info4 682 struct change_info4 { 683 bool atomic; 684 fattr4_change before; 685 fattr4_change after; 686 }; 688 This structure is used with the CREATE, LINK, REMOVE, RENAME 689 operations to let the client know value of the change attribute 690 for the directory in which the target file system object 691 resides. 693 Draft Specification NFS version 4 Protocol December 1999 695 clientaddr4 697 struct clientaddr4 { 698 /* see struct rpcb in RFC 1833 */ 699 string r_netid<>; /* network id */ 700 string r_addr<>; /* universal address */ 701 }; 703 The clientaddr4 structure is used as part of the SETCLIENT 704 operation to specify the address of either the client that is 705 using a clientid or as part of the call back registration. 707 cb_client4 709 struct cb_client4 { 710 unsigned int cb_program; 711 clientaddr4 cb_location; 712 }; 714 This structure is used by the client to inform the server of its 715 call back address; includes the program number and client 716 address. 718 nfs_client_id4 720 struct nfs_client_id4 { 721 opaque verifier[4]; 722 opaque id<>; 723 }; 725 This structure is part of the arguments to the SETCLIENTID 726 operation. 728 nfs_lockowner4 730 struct nfs_lockowner4 { 731 clientid4 clientid; 732 opaque owner<>; 733 }; 735 This structure is used to identify the owner of a OPEN share or 736 file lock. 738 Draft Specification NFS version 4 Protocol December 1999 740 3. RPC and Security Flavor 742 The NFS version 4 protocol is a Remote Procedure Call (RPC) 743 application that uses RPC version 2 and the corresponding eXternal 744 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 745 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 746 the mechanism to deliver stronger security for the NFS version 4 747 protocol. 749 3.1. Ports and Transports 751 Historically, NFS version 2 and version 3 servers have resided on 752 port 2049. The registered port 2049 [RFC1700] for the NFS protocol 753 should be the default configuration. Using the registered port for 754 NFS services means the NFS client will not need to use the RPC 755 binding protocols as described in [RFC1833]; this will allow NFS to 756 transit firewalls. 758 The transport used by the RPC service for the NFS version 4 protocol 759 MUST provide congestion control comparable to that defined for TCP in 760 [RFC2581]. If the operating environment implements TCP, the NFS 761 version 4 protocol SHOULD be supported over TCP. The NFS client and 762 server may use other transports if they support congestion control as 763 defined above and in those cases a mechanism may be provided to 764 override TCP usage in favor of another transport. 766 If TCP is used as the transport, the client and server SHOULD use 767 persistent connections. This will prevent the weakening of TCP's 768 congestion control via short lived connections. 770 3.2. Security Flavors 772 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 773 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 774 additional security flavor of RPCSEC_GSS has been introduced which 775 uses the functionality of GSS-API [RFC2078]. This allows for the use 776 of varying security mechanisms by the RPC layer without the 777 additional implementation overhead of adding RPC security flavors. 778 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 779 enable the mandatory security mechanism. The flavors AUTH_NONE, 780 AUTH_SYS, and AUTH_DH MAY be implemented as well. 782 3.2.1. Security mechanisms for NFS version 4 784 The use of RPCSEC_GSS requires selection of: mechanism, quality of 785 protection, and service (authentication, integrity, privacy). The 786 remainder of this document will refer to these three parameters of 788 Draft Specification NFS version 4 Protocol December 1999 790 the RPCSEC_GSS security as the security triple. 792 3.2.1.1. Kerberos V5 as security triple 794 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 795 implemented and provide the following security triples. 797 column descriptions: 799 1 == number of pseudo flavor 800 2 == name of pseudo flavor 801 3 == mechanism's OID 802 4 == mechanism's algorithm(s) 803 5 == RPCSEC_GSS service 805 1 2 3 4 5 806 ----------------------------------------------------------------------- 807 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 808 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 809 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 810 for integrity, 811 and 56 bit DES 812 for privacy. 814 Note that the pseudo flavor is presented here as a mapping aid to the 815 implementor. Because this NFS protocol includes a method to 816 negotiate security and it understands the GSS-API mechanism, the 817 pseudo flavor is not needed. The pseudo flavor is needed for NFS 818 version 3 since the security negotiation is done via the MOUNT 819 protocol. 821 For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please 822 see [RFC2623]. 824 3.2.1.2. LIPKEY as a security triple 826 The LIPKEY GSS-API mechanism as described in [RFCXXXX] MUST be 827 implemented and provide the following security triples. The 828 definition of the columns matches the previous subsection "Kerberos 829 V5 as security triple" 831 1 2 3 4 5 832 ----------------------------------------------------------------------- 833 390006 lipkey TBD negotiated rpc_gss_svc_none 834 390007 lipkey-i TBD negotiated rpc_gss_svc_integrity 835 390008 lipkey-p TBD negotiated rpc_gss_svc_privacy 837 Draft Specification NFS version 4 Protocol December 1999 839 The mechanism algorithm is listed as "negotiated". This is because 840 LIPKEY is layered on SPKM-3 and in SPKM-3 [RFCXXXX] the 841 confidentiality and integrity algorithms are negotiated. Since 842 SPKM-3 specifies HMAC-MD5 for integrity as MANDATORY, 128 bit 843 cast5CBC for confidentiality for privacy as MANDATORY, and further 844 specifies that HMAC-MD5 and cast5CBC MUST be listed first before 845 weaker algorithms, specifying "negotiated" in column 4 does not 846 impair interoperability. In the event an SPKM-3 does not support the 847 mandatory algorithms, the other peer is free to accept or reject the 848 GSS-API context creation. 850 Because SPKM-3 negotiates the algorithms, subsequent calls to 851 LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality 852 of protection value of 0 (zero). See section 5.2 of [RFC2025] for an 853 explanation. 855 LIPKEY uses SPKM-3 to create a secure channel in which to pass a user 856 name and password from the client to the user. Once the user name 857 and password have been accepted by the server, calls to the LIPKEY 858 context are redirected to the SPKM-3 context. See [RFCXXXX] for more 859 details. 861 3.2.1.3. SPKM-3 as a security triple 863 The SPKM-3 GSS-API mechanism as described in [RFCXXXX] MUST be 864 implemented and provide the following security triples. The 865 definition of the columns matches the previous subsection "Kerberos 866 V5 as security triple". 868 1 2 3 4 5 869 ----------------------------------------------------------------------- 870 390009 spkm3 TBD negotiated rpc_gss_svc_none 871 390010 spkm3i TBD negotiated rpc_gss_svc_integrity 872 390011 spkm3p TBD negotiated rpc_gss_svc_privacy 874 For a discussion as to why the mechanism algorithm is listed as 875 "negotiated", see the previous section "LIPKEY as a security triple." 877 Because SPKM-3 negotiates the algorithms, subsequent calls to SPKM- 878 3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality of 879 protection value of 0 (zero). See section 5.2 of [RFC2025] for an 880 explanation. 882 Even though LIPKEY is layered onto SPKM-3, SPKM-3 is specified as a 883 mandatory set of triples to handle the situation when the initiator 884 (the client) is anonymous. If the initiator is anonymous, there will 885 not be a user name and password to send to the target (the server). 887 Draft Specification NFS version 4 Protocol December 1999 889 3.3. Security Negotiation 891 With the NFS version 4 server potentially offering multiple security 892 mechanisms, the client needs a method to determine or negotiate which 893 mechanism is to be used for its communication with the server. The 894 NFS server may have multiple points within its file system name space 895 that are available for use by NFS clients. In turn the NFS server 896 may be configured such that each of these entry points may have 897 different or multiple security mechanisms in use. 899 The security negotiation between client and server must be done with 900 a secure channel to eliminate the possibility of a third party 901 intercepting the negotiation sequence and forcing the client and 902 server to choose a lower level of security than required or desired. 904 3.3.1. Security Error 906 Based on the assumption that each NFS version 4 client and server 907 must support a minimum set of security (i.e. LIPKEY, SPKM-3, and 908 Kerberos-V5 all under RPCSEC_GSS), the NFS client will start its 909 communication with the server with one of the minimal security 910 triples. During communication with the server, the client may 911 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 912 server to notify the client that the security triple currently being 913 used is not appropriate for access to the server's file system 914 resources. The client is then responsible for determining what 915 security triples are available at the server and choose one which is 916 appropriate for the client. 918 3.3.2. SECINFO 920 The new SECINFO operation will allow the client to determine, on a 921 per filehandle basis, what security triple is to be used for server 922 access. In general, the client will not have to use the SECINFO 923 procedure except during initial communication with the server or when 924 the client crosses policy boundaries at the server. It is possible 925 that the server's policies change during the client's interaction 926 therefore forcing the client to negotiate a new security triple. 928 Draft Specification NFS version 4 Protocol December 1999 930 4. Filehandles 932 The filehandle in the NFS protocol is a per server unique identifier 933 for a file system object. The contents of the filehandle are opaque 934 to the client. Therefore, the server is responsible for translating 935 the filehandle to an internal representation of the file system 936 object. Since the filehandle is the client's reference to an object 937 and the client may cache this reference, the server should not reuse 938 a filehandle for another file system object. If the server needs to 939 reuse a filehandle value, the time elapsed before reuse SHOULD be 940 large enough that it is likely the client no longer has a cached copy 941 of the reused filehandle value. 943 4.1. Obtaining the First Filehandle 945 The operations of the NFS protocol are defined in terms of one or 946 more filehandles. Therefore, the client needs a filehandle to 947 initiate communication with the server. With the NFS version 2 948 protocol [RFC1094] and the NFS version 3 protocol [RFC1813], there 949 exists an ancillary protocol to obtain this first filehandle. The 950 MOUNT protocol, RPC program number 100005, provides the mechanism of 951 translating a string based file system path name to a filehandle 952 which can then be used by the NFS protocols. 954 The MOUNT protocol has deficiencies in the area of security and use 955 via firewalls. This is one reason that the use of the public 956 filehandle was introduced in [RFC2054] and [RFC2055]. With the use 957 of the public filehandle in combination with the LOOKUP procedure in 958 the NFS version 2 and 3 protocols, it has been demonstrated that the 959 MOUNT protocol is unnecessary for viable interaction between NFS 960 client and server. 962 Therefore, the NFS version 4 protocol will not use an ancillary 963 protocol for translation from string based path names to a 964 filehandle. Two special filehandles will be used as starting points 965 for the NFS client. 967 4.1.1. Root Filehandle 969 The first of the special filehandles is the ROOT filehandle. The 970 ROOT filehandle is the "conceptual" root of the file system name 971 space at the NFS server. The client uses or starts with the ROOT 972 filehandle by employing the PUTROOTFH operation. The PUTROOTFH 973 operation instructs the server to set the "current" filehandle to the 974 ROOT of the server's file tree. Once this PUTROOTFH operation is 975 used, the client can then traverse the entirety of the server's file 977 Draft Specification NFS version 4 Protocol December 1999 979 tree with the LOOKUP procedure. A complete discussion of the server 980 name space is in the section "NFS Server Name Space". 982 4.1.2. Public Filehandle 984 The second special filehandle is the PUBLIC filehandle. Unlike the 985 ROOT filehandle, the PUBLIC filehandle may be bound or represent an 986 arbitrary file system object at the server. The server is 987 responsible for this binding. It may be that the PUBLIC filehandle 988 and the ROOT filehandle refer to the same file system object. 989 However, it is up to the administrative software at the server and 990 the policies of the server administrator to define the binding of the 991 PUBLIC filehandle and server file system object. The client may not 992 make any assumptions about this binding. 994 4.2. Filehandle Types 996 In the NFS version 2 and 3 protocols, there was one type of 997 filehandle with a single set of semantics. The NFS version 4 998 protocol introduces a new type of filehandle in an attempt to 999 accommodate certain server environments. The first type of 1000 filehandle is 'persistent'. The semantics of a persistent filehandle 1001 are the same as the filehandles of the NFS version 2 and 3 protocols. 1002 The second or new type of filehandle is the "volatile" filehandle. 1004 The volatile filehandle type is being introduced to address server 1005 functionality or implementation issues which prevent correct or 1006 feasible implementation of a persistent filehandle. Some server 1007 environments do not provide a file system level invariant that can be 1008 used to construct a persistent filehandle. The underlying server 1009 file system may not provide the invariant or the server's file system 1010 programming interfaces may not provide access to the needed 1011 invariant. Volatile filehandles may ease the implementation of 1012 server functionality such as hierarchical storage management or file 1013 system reorganization or migration. However, the volatile filehandle 1014 increases the implementation burden for the client. However this 1015 increased burden is deemed acceptable based on the overall gains 1016 achieved by the protocol. 1018 Since the client will have different paths of logic to handle 1019 persistent and volatile filehandles, a file attribute is defined 1020 which may be used by the client to determine the filehandle types 1021 being returned by the server. 1023 Draft Specification NFS version 4 Protocol December 1999 1025 4.2.1. General Properties of a Filehandle 1027 The filehandle contains all the information the server needs to 1028 distinguish an individual file. To the client, the filehandle is 1029 opaque. The client stores filehandles for use in a later request and 1030 can compare two filehandles from the same server for equality by 1031 doing a byte-by-byte comparison. However, the client MUST NOT 1032 otherwise interpret the contents of filehandles. If two filehandles 1033 from the same server are equal, they MUST refer to the same file. If 1034 they are not equal, no conclusions can be drawn. Servers SHOULD try 1035 to maintain a one-to-one correspondence between filehandles and files 1036 but this is not required. Clients MUST only use filehandle 1037 comparisons only to improve performance, not for correct behavior. 1038 Further discussion of filehandle and attribute comparison in the 1039 context of data caching is presented in the section "Data Caching and 1040 File Identity". 1042 As an example, in the case that two different path names when 1043 traversed at the server terminate at the same file system object, the 1044 server SHOULD return the same filehandle for each path. This can 1045 occur if a hard link is used to create two file names which refer to 1046 the same underlying file object and associated data. For example, if 1047 paths /a/b/c and /a/d/c refer to the same file, the server SHOULD 1048 return the same filehandle for both path names traversals. 1050 4.2.2. Persistent Filehandle 1052 A persistent filehandle is defined as having a persistent value for 1053 the lifetime of the file system object to which it refers. Once the 1054 server creates the filehandle for a file system object, the server 1055 MUST accept the same filehandle for the object for the lifetime of 1056 the object. If the server restarts or reboots, or the file system is 1057 migrated, the NFS server must honor the same filehandle value as it 1058 did in the server's previous instantiation. 1060 The persistent filehandle will be become stale or invalid when the 1061 file system object is removed. When the server is presented with a 1062 persistent filehandle that refers to a deleted object, it MUST return 1063 an error of NFS4ERR_STALE. A filehandle may become stale when the 1064 file system containing the object is no longer available. The file 1065 system may become unavailable if it exists on removable media and the 1066 media is no longer available at the server or the file system in 1067 whole has been destroyed or the file system has simply been removed 1068 from the server's name space (i.e. unmounted in a Unix environment). 1070 Draft Specification NFS version 4 Protocol December 1999 1072 4.2.3. Volatile Filehandle 1074 A volatile filehandle does not share the same longevity attributes of 1075 the persistent filehandle. The server may determine that a volatile 1076 filehandle is no longer valid at many different points in time. If 1077 the server can definitively determine that a volatile filehandle 1078 refers to an object that has been removed, the server should return 1079 NFS4ERR_STALE to the client (as is the case for persistent 1080 filehandles). In all other cases where the server determines that a 1081 volatile filehandle can no longer be used, it should return an error 1082 of NFS4ERR_FHEXPIRED. 1084 The mandatory attribute "fh_expire_type" is used by the client to 1085 determine what type of filehandle the server is providing for a 1086 particular file system. This attribute is a bitmask with the 1087 following values: 1089 FH4_PERSISTENT 1090 The filehandle is valid until the object is removed from the 1091 file system. The server will not return NFS4ERR_FHEXPIRED for 1092 this filehandle. 1094 FH4_NOEXPIRE_WITH_OPEN 1095 The filehandle will not expire while client has the file open. 1096 If this bit is set, then the values defined as follows do not 1097 impact expiration while the file is open. Once the file is 1098 closed or if the FH4_NOEXPIRE_WITH_OPEN bit is false, the rest 1099 of the volatile related bits apply. 1101 FH4_VOLATILE_ANY 1102 The filehandle may expire at any time. 1104 FH4_VOL_MIGRATION 1105 The filehandle may expire during file system migration. May 1106 only be set if FH4_VOLATILE_ANY is not set. 1108 FH4_VOL_RENAME 1109 The filehandle may expire due to a rename. This includes a 1110 rename by the requesting client or a rename by another client. 1111 May only be set if FH4_VOLATILE_ANY is not set. 1113 Servers which provide volatile filehandles should deny a RENAME or 1114 REMOVE that would effect an OPEN file or any of the components 1115 leading to the OPEN file. In addition, the server should deny all 1116 RENAME or REMOVE requests during the grace or lease period upon 1117 server restart. 1119 Draft Specification NFS version 4 Protocol December 1999 1121 4.2.4. One Method of Constructing a Volatile Filehandle 1123 As mentioned, in some instances a filehandle is stale (no longer 1124 valid; perhaps because the file was removed from the server) or it is 1125 expired (the underlying file is valid but since the filehandle is 1126 volatile, it may have expired). Thus the server needs to be able to 1127 return NFS4ERR_STALE in the former case and NFS4ERR_FHEXPIRED in the 1128 latter case. This can be done by careful construction of the volatile 1129 filehandle. One possible implementation follows. 1131 A volatile filehandle, while opaque to the client could contain: 1133 [volatile bit = 1 | server boot time | slot | generation number] 1135 o slot is an index in the server volatile filehandle table 1137 o generation number is the generation number for the table 1138 entry/slot 1140 If the server boot time is less than the current server boot time, 1141 return NFS4ERR_FHEXPIRED. If slot is out of range, return 1142 NFS4ERR_BADHANDLE. If the generation number does not match, return 1143 NFS4ERR_FHEXPIRED. 1145 When the server reboots, the table is gone (it is volatile). 1147 If volatile bit is 0, then it is a persistent filehandle with a 1148 different structure following it. 1150 4.3. Client Recovery from Filehandle Expiration 1152 If possible, the client SHOULD recover from the receipt of an 1153 NFS4ERR_FHEXPIRED error. The client must take on additional 1154 responsibility so that it may prepare itself to recover from the 1155 expiration of a volatile filehandle. If the server returns 1156 persistent filehandles, the client does not need these additional 1157 steps. 1159 For volatile filehandles, most commonly the client will need to store 1160 the component names leading up to and including the file system 1161 object in question. With these names, the client should be able to 1162 recover by finding a filehandle in the name space that is still 1163 available or by starting at the root of the server's file system name 1164 space. 1166 If the expired filehandle refers to an object that has been removed 1168 Draft Specification NFS version 4 Protocol December 1999 1170 from the file system, obviously the client will not be able to 1171 recover from the expired filehandle. 1173 It is also possible that the expired filehandle refers to a file that 1174 has been renamed. If the file was renamed by another client, again 1175 it is possible that the original client will not be able to recover. 1176 However, in the case that the client itself is renaming the file and 1177 the file is open, it is possible that the client may be able to 1178 recover. The client can determine the new path name based on the 1179 processing of the rename request. The client can then regenerate the 1180 new filehandle based on the new path name. The client could also use 1181 the compound operation mechanism to construct a set of operations 1182 like: 1183 RENAME A B 1184 LOOKUP B 1185 GETFH 1187 Draft Specification NFS version 4 Protocol December 1999 1189 5. File Attributes 1191 To meet the requirements of extensibility and increased 1192 interoperability with non-Unix platforms, attributes must be handled 1193 in a flexible manner. The NFS Version 3 fattr3 structure contains a 1194 fixed list of attributes that not all clients and servers are able to 1195 support or care about. The fattr3 structure can not be extended as 1196 new needs arise and it provides no way to indicate non-support. With 1197 the NFS Version 4 protocol, the client will be able to ask what 1198 attributes the server supports and will be able to request only those 1199 attributes in which it is interested. 1201 To this end, attributes will be divided into three groups: mandatory, 1202 recommended, and named. Both mandatory and recommended attributes 1203 are supported in the NFS version 4 protocol by a specific and well- 1204 defined encoding and are identified by number. They are requested by 1205 setting a bit in the bit vector sent in the GETATTR request; the 1206 server response includes a bit vector to list what attributes were 1207 returned in the response. New mandatory or recommended attributes 1208 may be added to the NFS protocol between major revisions by 1209 publishing a standards-track RFC which allocates a new attribute 1210 number value and defines the encoding for the attribute. See the 1211 section "Minor Versioning" for further discussion. 1213 Named attributes are accessed by the new OPENATTR operation, which 1214 accesses a hidden directory of attributes associated with a file 1215 system object. OPENATTR takes a filehandle for the object and 1216 returns the filehandle for the attribute hierarchy. The filehandle 1217 for the named attributes is a directory object accessible by LOOKUP 1218 or READDIR and contains files whose names represent the named 1219 attributes and whose data bytes are the value of the attribute. For 1220 example: 1222 LOOKUP "foo" ; look up file 1223 GETATTR attrbits 1224 OPENATTR ; access foo's named attributes 1225 LOOKUP "x11icon" ; look up specific attribute 1226 READ 0,4096 ; read stream of bytes 1228 Named attributes are intended primarily for data needed by 1229 applications rather than by an NFS client implementation. NFS 1230 implementors are strongly encouraged to define their new attributes 1231 as recommended attributes by bringing them to the IETF standards- 1232 track process. 1234 The set of attributes which are classified as mandatory is 1236 Draft Specification NFS version 4 Protocol December 1999 1238 deliberately small since servers must do whatever it takes to support 1239 them. The recommended attributes may be unsupported; though a server 1240 should support as many as it can. Attributes are deemed mandatory if 1241 the data is both needed by a large number of clients and is not 1242 otherwise reasonably computable by the client when support is not 1243 provided on the server. 1245 5.1. Mandatory Attributes 1247 These MUST be supported by every NFS Version 4 client and server in 1248 order to ensure a minimum level of interoperability. The server must 1249 store and return these attributes and the client must be able to 1250 function with an attribute set limited to these attributes. With 1251 just the mandatory attributes some client functionality may be 1252 impaired or limited in some ways. A client may ask for any of these 1253 attributes to be returned by setting a bit in the GETATTR request and 1254 the server must return their value. 1256 5.2. Recommended Attributes 1258 These attributes are understood well enough to warrant support in the 1259 NFS Version 4 protocol. However, they may not be supported on all 1260 clients and servers. A client may ask for any of these attributes to 1261 be returned by setting a bit in the GETATTR request but must handle 1262 the case where the server does not return them. A client may ask for 1263 the set of attributes the server supports and should not request 1264 attributes the server does not support. A server should be tolerant 1265 of requests for unsupported attributes and simply not return them 1266 rather than considering the request an error. It is expected that 1267 servers will support all attributes they comfortably can and only 1268 fail to support attributes which are difficult to support in their 1269 operating environments. A server should provide attributes whenever 1270 they don't have to "tell lies" to the client. For example, a file 1271 modification time should be either an accurate time or should not be 1272 supported by the server. This will not always be comfortable to 1273 clients but it seems that the client has a better ability to 1274 fabricate or construct an attribute or do without the attribute. 1276 5.3. Named Attributes 1278 These attributes are not supported by direct encoding in the NFS 1279 Version 4 protocol but are accessed by string names rather than 1280 numbers and correspond to an uninterpreted stream of bytes which are 1281 stored with the file system object. The namespace for these 1282 attributes may be accessed by using the OPENATTR operation. The 1284 Draft Specification NFS version 4 Protocol December 1999 1286 OPENATTR operation returns a filehandle for a virtual "attribute 1287 directory" and further perusal of the name space may be done using 1288 READDIR and LOOKUP operations on this filehandle. Named attributes 1289 may then be examined or changed by normal READ and WRITE and CREATE 1290 operations on the filehandles returned from READDIR and LOOKUP. 1291 Named attributes may have attributes. For example, a security label 1292 may have access control information in its own right. 1294 It is recommended that servers support arbitrary named attributes. A 1295 client should not depend on the ability to store any named attributes 1296 in the server's file system. If a server does support named 1297 attributes, a client which is also able to handle them should be able 1298 to copy a file's data and meta-data with complete transparency from 1299 one location to another; this would imply that there should be no 1300 attribute names which will be considered illegal by the server. 1302 Names of attributes will not be controlled by a standards body. 1303 However, vendors and application writers are encouraged to register 1304 attribute names and the interpretation and semantics of the stream of 1305 bytes via informational RFCs so that other implementations may 1306 interoperate where common interests exist. 1308 Draft Specification NFS version 4 Protocol December 1999 1310 5.4. Mandatory Attributes - Definitions 1312 Name # DataType Access Description 1313 ___________________________________________________________________ 1314 supp_attr 0 bitmap READ The bit vector which 1315 would retrieve all 1316 mandatory and 1317 recommended attributes 1318 which may be requested 1319 for this object. 1321 The client must ask 1322 this question to 1323 request correct 1324 attributes. 1326 object_type 1 nfs4_ftype READ The type of the object 1327 (file, directory, 1328 symlink) 1330 The client cannot 1331 handle object 1332 correctly without 1333 type. 1335 fh_expire_type 2 uint32 READ Server uses this to 1336 specify filehandle 1337 expiration behavior to 1338 the client. See the 1339 section "Filehandles" 1340 for additional 1341 description. 1343 Draft Specification NFS version 4 Protocol December 1999 1345 change 3 uint64 READ A value created by the 1346 server that the client 1347 can use to determine 1348 if file data, 1349 directory contents or 1350 attributes of the 1351 object have been 1352 modified. The server 1353 may return the 1354 object's time_modify 1355 attribute for this 1356 attribute's value but 1357 only if the file 1358 system object can not 1359 be updated more 1360 frequently than the 1361 resolution of 1362 time_modify. 1364 object_size 4 uint64 R/W The size of the object 1365 in bytes. 1367 Could be very 1368 expensive to derive, 1369 likely to be 1370 available. 1372 link_support 5 boolean READ Does the object's file 1373 system supports hard 1374 links? 1376 Server can easily 1377 determine if links are 1378 supported. 1380 symlink_support 6 boolean READ Does the object's file 1381 system supports 1382 symbolic links? 1384 Server can easily 1385 determine if links are 1386 supported. 1388 named_attr 7 boolean READ Does this object have 1389 named attributes? 1391 Draft Specification NFS version 4 Protocol December 1999 1393 fsid 8 fsid4 READ Unique file system 1394 identifier for the 1395 file system holding 1396 this object. fsid 1397 contains major and 1398 minor components each 1399 of which are uint64. 1401 unique_handles 9 boolean READ Are two distinct 1402 filehandles guaranteed 1403 to refer to two 1404 different file system 1405 objects? 1407 lease_time 10 nfs_lease4 READ Duration of leases at 1408 server in seconds. 1410 rdattr_error 11 enum READ Error returned from 1411 getattr during 1412 readdir. 1414 Draft Specification NFS version 4 Protocol December 1999 1416 5.5. Recommended Attributes - Definitions 1418 Name # Data Type Access Description 1419 _____________________________________________________________________ 1420 ACL 12 nfsace4<> R/W The access control 1421 list for the object. 1422 [The nature and 1423 format of ACLs is 1424 still to be 1425 determined.] 1427 aclsupport 13 uint32 READ Indicates what ACLs 1428 are supported on the 1429 current file system. 1431 archive 14 boolean R/W Whether or not this 1432 file has been 1433 archived since the 1434 time of last 1435 modification 1436 (deprecated in favor 1437 of backup_time). 1439 cansettime 15 boolean READ Whether or not this 1440 object's file system 1441 can fill in the times 1442 on a SETATTR request 1443 without an explicit 1444 time. 1446 case_insensitive 16 boolean READ Are filename 1447 comparisons on this 1448 file system case 1449 insensitive? 1451 case_preserving 17 boolean READ Is filename case on 1452 this file system 1453 preserved? 1455 Draft Specification NFS version 4 Protocol December 1999 1457 chown_restricted 18 boolean READ If TRUE, the server 1458 will reject any 1459 request to change 1460 either the owner or 1461 the group associated 1462 with a file if the 1463 caller is not a 1464 privileged user (for 1465 example, "root" in 1466 Unix operating 1467 environments or in NT 1468 the "Take Ownership" 1469 privilege) 1471 filehandle 19 nfs4_fh READ The filehandle of 1472 this object 1473 (primarily for 1474 readdir requests). 1476 fileid 20 uint64 READ A number uniquely 1477 identifying the file 1478 within the file 1479 system. 1481 files_avail 21 uint64 READ File slots available 1482 to this user on the 1483 file system 1484 containing this 1485 object - this should 1486 be the smallest 1487 relevant limit. 1489 files_free 22 uint64 READ Free file slots on 1490 the file system 1491 containing this 1492 object - this should 1493 be the smallest 1494 relevant limit. 1496 files_total 23 uint64 READ Total file slots on 1497 the file system 1498 containing this 1499 object. 1501 Draft Specification NFS version 4 Protocol December 1999 1503 fs_locations 24 fs_locations READ Locations where this 1504 file system may be 1505 found. If the server 1506 returns NFS4ERR_MOVED 1507 as an error, this 1508 attribute must be 1509 supported. 1511 hidden 25 boolean R/W Is file considered 1512 hidden with respect 1513 to the WIN32 API. 1515 homogeneous 26 boolean READ Whether or not this 1516 object's file system 1517 is homogeneous, i.e. 1518 whether pathconf is 1519 the same for all file 1520 system objects. 1522 maxfilesize 27 uint64 READ Maximum supported 1523 file size for the 1524 file system of this 1525 object. 1527 maxlink 28 uint32 READ Maximum number of 1528 links for this 1529 object. 1531 maxname 29 uint32 READ Maximum filename size 1532 supported for this 1533 object. 1535 maxread 30 uint64 READ Maximum read size 1536 supported for this 1537 object. 1539 Draft Specification NFS version 4 Protocol December 1999 1541 maxwrite 31 uint64 READ Maximum write size 1542 supported for this 1543 object. This 1544 attribute SHOULD be 1545 supported if the file 1546 is writable. Lack of 1547 this attribute can 1548 lead to the client 1549 either wasting 1550 bandwidth or not 1551 receiving the best 1552 performance. 1554 mime_type 32 utf8<> R/W MIME body 1555 type/subtype of this 1556 object. 1558 mode 33 mode4 R/W Unix-style permission 1559 bits for this object 1560 (deprecated in favor 1561 of ACLs) 1563 no_trunc 34 boolean READ If a name longer than 1564 name_max is used, 1565 will an error be 1566 returned or will the 1567 name be truncated? 1569 numlinks 35 uint32 READ Number of links to 1570 this object. 1572 owner 36 utf8<> R/W The string name of 1573 the owner of this 1574 object. 1576 owner_group 37 utf8<> R/W The string name of 1577 the group of the 1578 owner of this object. 1580 quota_hard 38 uint64 READ For definition see 1581 "Quota Attributes" 1582 section below. 1584 quota_soft 39 uint64 READ For definition see 1585 "Quota Attributes" 1586 section below. 1588 Draft Specification NFS version 4 Protocol December 1999 1590 quota_used 40 uint64 READ For definition see 1591 "Quota Attributes" 1592 section below. 1594 rawdev 41 specdata4 READ Raw device 1595 identifier. 1597 space_avail 42 uint64 READ Disk space in bytes 1598 available to this 1599 user on the file 1600 system containing 1601 this object - this 1602 should be the 1603 smallest relevant 1604 limit. 1606 space_free 43 uint64 READ Free disk space in 1607 bytes on the file 1608 system containing 1609 this object - this 1610 should be the 1611 smallest relevant 1612 limit. 1614 space_total 44 uint64 READ Total disk space in 1615 bytes on the file 1616 system containing 1617 this object. 1619 space_used 45 uint64 READ Number of file system 1620 bytes allocated to 1621 this object. 1623 system 46 boolean R/W Is this file is a 1624 system file with 1625 respect to the WIN32 1626 API. 1628 time_access 47 nfstime4 R/W The time of last 1629 access to the object. 1631 time_backup 48 nfstime4 R/W The time of last 1632 backup of the object. 1634 Draft Specification NFS version 4 Protocol December 1999 1636 time_create 49 nfstime4 R/W The time of creation 1637 of the object. This 1638 attribute does not 1639 have any relation to 1640 the traditional Unix 1641 file attribute 1642 "ctime" or "change 1643 time". 1645 time_delta 50 nfstime4 READ Smallest useful 1646 server time 1647 granularity. 1649 time_metadata 51 nfstime4 R/W The time of last 1650 meta-data 1651 modification of the 1652 object. 1654 time_modify 52 nfstime4 R/W The time since the 1655 epoch of last 1656 modification to the 1657 object. 1659 version 53 utf8<> R/W Version number of 1660 this document. 1662 volatility 54 nfstime4 READ Approximate time 1663 until next expected 1664 change on this file 1665 system, as a measure 1666 of volatility. 1668 5.6. Interpreting owner and owner_group 1670 The recommended attributes "owner" and "owner_group" are represented 1671 in terms of a UTF-8 string. To avoid a representation that is tied 1672 to a particular underlying implementation at the client or server, 1673 the use of the UTF-8 string has been chosen. Note that section 6.1 1674 of [RFC2624] provides additional rationale. It is expected that the 1675 client and server will have their own local representation of owner 1676 and owner_group that is used for local storage or presentation to the 1677 end user. Therefore, it is expected that the when these attributes 1678 are transferred between the client and server that the local 1679 representation is translated to a syntax of the form 1681 Draft Specification NFS version 4 Protocol December 1999 1683 "user@dns_domain". This will allow for a client and server that do 1684 not use the same local representation the ability to translate to a 1685 common syntax that can be interpreted by both. 1687 The translation is not specified as part of the protocol. This 1688 allows various solutions to be employed. For example, a local 1689 translation table may be consulted that maps between a numeric id to 1690 the user@dns_domain syntax. A name service may also be used to 1691 accomplish the translation. The "dns_domain" portion of the owner 1692 string is meant to be a DNS domain name. For example, user@ietf.org. 1694 In the case where there is no translation available to the client or 1695 server, the attribute value must be constructed without the "@". 1696 Therefore, the absence of the @ from the owner or owner_group 1697 attribute signifies that no translation was available and the 1698 receiver of the attribute should not place any special meaning with 1699 the attribute value. Even though the attribute value can not be 1700 translated, it may still be useful. In the case of a client, the 1701 attribute string may be used for local display of ownership. 1703 5.7. Quota Attributes 1705 For the attributes related to file system quotas, the following 1706 definitions apply: 1708 quota_avail_soft 1709 The value in bytes which represents the amount of extra disc 1710 space that can be allocated to this file before the user may 1711 reasonably be warned. It is understood that this space may be 1712 consumed by allocations to other files though there is a rule as 1713 to which other files. 1715 quota_avail_hard 1716 The value in bytes which represent the amount of extra disc 1717 space that can be allocated to this file before further 1718 allocations will be declined. It is understood that this space 1719 may be consumed by allocations to other files. 1721 quota_used 1722 The value in bytes which represent the amount of disc space used 1723 by this file and possibly a number of other similar files, where 1724 the set of "similar" files meets at least the criterion that 1725 allocating space to any file in the set will reduce the 1726 "quota_avail_hard" of every other file in the set. 1728 Draft Specification NFS version 4 Protocol December 1999 1730 Note that there may be a number of distinct but overlapping sets 1731 of files for which a quota_used value is maintained. E.g. "all 1732 files with a given owner", "all files with a given group owner". 1733 etc. 1735 The server is at liberty to choose any of those sets, but should 1736 do so in a repeatable way. The rule may be configured per- 1737 filesystem, or may be "choose the set with the smallest quota". 1739 5.8. Access Control Lists 1741 The NFS ACL attribute is an array of access control entries (ACE). 1742 There are various access control entry types. The server is able to 1743 communicate which ACE types are support by returning the appropriate 1744 value within the aclsupport attribute. The types of ACEs are defined 1745 as follows: 1747 Type Description 1748 _____________________________________________________ 1749 ALLOW Explicitly grants the access defined in 1750 acemask4 to the file or directory. 1752 DENY Explicitly denies the access defined in 1753 acemask4 to the file or directory. 1755 AUDIT LOG (system dependant) any access 1756 attempt to a file or directory which 1757 uses an access method which is a subset 1758 of acemask4. 1760 ALARM Generate a system ALARM (system 1761 dependant) when any access attempt is 1762 made to a file or directory which is a 1763 subset of acemask4 1765 The NFS ACE attribute is defined as follows: 1767 typedef uint32_t acetype4; 1768 typedef uint32_t aceflag4; 1769 typedef uint32_t acemask4; 1771 struct nfsace4 { 1772 acetype4 type; 1773 aceflag4 flag; 1774 acemask4 access_mask; 1776 Draft Specification NFS version 4 Protocol December 1999 1778 utf8string who; 1779 }; 1781 To determine if an ACCESS or OPEN request succeeds each nfsace4 entry 1782 is processed in order by the server. Only ACEs which have a "who" 1783 that matches the requester are considered. Each ACE is processed 1784 until all of the bits of the requester's access have been ALLOWED. 1785 Once a bit (see below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it 1786 is no longer considered in the processing of later ACEs. If an 1787 ACCESS_DENIED_ACE is encountered where the requester's mode still has 1788 unALLOWED bits in common with the "access_mask" of the ACE, the 1789 request is denied. 1791 5.8.1. ACE type 1793 The semantics of the "type" field follow the descriptions provided 1794 above. 1796 5.8.2. ACE flag 1798 The "flag" field contains values based on the following descriptions. 1800 ACE4_FILE_INHERIT_ACE 1802 Can be placed on a directory and indicates that this ACE should be 1803 added to each new non-directory file created. 1805 ACE4_DIRECTORY_INHERIT_ACE 1807 Can be placed on a directory and indicates that this ACE should be 1808 added to each new directory created. 1810 ACE4_INHERIT_ONLY_ACE 1812 Can be placed on a directory but does not apply to the directory, 1813 only to newly created files/directories as specified by the above two 1814 flags. 1816 ACE4_NO_PROPAGATE_INHERIT_ACE 1818 Can be placed on a directory. Normally when a new directory is 1819 created and an ACE exists on the parent directory which is marked 1821 Draft Specification NFS version 4 Protocol December 1999 1823 ACL4_DIRECTORY_INHERIT_ACE, two ACEs are placed on the new directory. 1824 One for the directory itself and one which is an inheritable ACE for 1825 newly created directories. This flag tells the O/S to not place an 1826 ACE on the newly created directory which is inheritable by 1827 subdirectories of the created directory. 1829 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 1831 ACL4_FAILED_ACCESS_ACE_FLAG 1833 Both indicate for AUDIT and ALARM which state to log the event. On 1834 every ACCESS or OPEN call which occurs on a file or directory which 1835 has an ACL that is of type ACE4_SYSTEM_AUDIT_ACE_TYPE or 1836 ACE4_SYSTEM_ALARM_ACE_TYPE, the attempted access is compared to the 1837 ace4mask of these ACLs. If the access is a subset of ace4mask and the 1838 identifier match, an AUDIT trail or an ALARM is generated. By 1839 default this happens regardless of the success or failure of the 1840 ACCESS or OPEN call. 1842 The flag ACE4_SUCCESSFUL_ACCESS_ACE_FLAG only produces the AUDIT or 1843 ALARM if the ACCESS or OPEN call is successful. The 1844 ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS 1845 or OPEN call fails. 1847 ACE4_IDENTIFIER_GROUP 1849 Indicates that the "who" refers to a GROUP as defined under Unix. 1851 5.8.3. ACE Access Mask 1853 The access_mask field contains values based on the following: 1855 Access Description 1856 _______________________________________________________________ 1857 READ_DATA Permission to read the data of the file 1858 LIST_DIRECTORY Permission to list the contents of a 1859 directory 1860 WRITE_DATA Permission to modify the file's data 1861 ADD_FILE Permission to add a new file to a 1862 directory 1863 APPEND_DATA Permission to append data to a file 1865 Draft Specification NFS version 4 Protocol December 1999 1867 ADD_SUBDIRECTORY Permission to create a subdirectory to a 1868 directory 1869 READ_STREAMS Permission to read the additional 1870 streams of a file 1871 WRITE_STREAMS Permission to write the additional 1872 streams of a file 1873 EXECUTE Permission to execute a file 1874 DELETE_CHILD Permission to delete a file or directory 1875 within a directory 1876 READ_ATTRIBUTES The ability to read basic attributes 1877 (non-acls) of a file 1878 WRITE_ATTRIBUTES Permission to change basic attributes 1879 (non-acls) of a file 1881 DELETE Permission to Delete the File, IF FILE 1882 BASED 1883 READ_ACL Permission to Read the ACL 1884 WRITE_ACL Permission to Write the ACL 1885 WRITE_OWNER Permission to change the owner 1886 SYNCHRONIZE Allow the forcing of mutual-exclusion to 1887 the file 1889 5.8.4. ACE who 1891 There are several special identifiers ("who") which need to be 1892 understood universally. Some of these identifiers cannot be 1893 understood when an NFS client accesses the server, but have meaning 1894 when a local process accesses the file. The ability to display and 1895 modify these permissions is permitted over NFS. 1897 Who Description 1898 _______________________________________________________________ 1899 "OWNER" The owner of the file. 1900 "GROUP" The group associated with the file. 1901 "EVERYONE" The world. 1902 "INTERACTIVE" Accessed from an interactive terminal. 1903 "NETWORK" Accessed via the network. 1904 "DIALUP" Accessed as a dialup user to the server. 1905 "BATCH" Accessed from a batch job. 1906 "ANONYMOUS" Accessed without any authentication. 1907 "AUTHENTICATED" Any authenticated user (opposite of 1908 ANONYMOUS) 1909 "SERVICE" Access from a system service. 1911 Draft Specification NFS version 4 Protocol December 1999 1913 To avoid conflict these special identifiers should be of the form 1914 "xxxx@". For example: ANONYMOUS@. 1916 Draft Specification NFS version 4 Protocol December 1999 1918 6. File System Migration and Replication 1920 With the use of the recommended attribute "fs_locations", the NFS 1921 version 4 server has a method of providing file system migration or 1922 replication services. For the purposes of migration and replication, 1923 a file system will be defined as all files that share a given fsid 1924 (major and minor values are the same). 1926 The fs_locations attribute provides a list of file system locations. 1927 These locations are specified by providing the server name (either 1928 DNS domain or IP address) and the path name representing the root of 1929 the file system. Depending on the type of service being provided, 1930 the list will provide a new or alternate locations for the file 1931 system. The client will use this information to redirect its 1932 requests to the new server. 1934 6.1. Replication 1936 It is expected that file system replication will be used in the case 1937 of read-only data. Typically, the file system will be replicated 1938 amongst two or more servers. The fs_locations attribute will provide 1939 the list of these locations to the client. On first access of the 1940 file system, the client should obtain the value of the fs_locations 1941 attribute. If, in the future, the client finds the server 1942 unresponsive, the client may attempt to use another server specified 1943 by fs_locations. 1945 If applicable, the client must take the appropriate steps to recover 1946 valid filehandles from the new server. This is described in more 1947 detail in the following sections. 1949 6.2. Migration 1951 File system migration is used to move a file system from one server 1952 to another. Migration is typically used for a file system that is 1953 writable and has a single copy. The expected use of migration is for 1954 load balancing or general resource reallocation. The protocol does 1955 not specify how the file system will be moved between servers. This 1956 server-to-server transfer mechanism is left to the server 1957 implementor. However, the method used to communicate the migration 1958 event between client and server is specified here. 1960 Once the servers participating in the migration have completed the 1961 move of the file system, the error NFS4ERR_MOVED will be returned for 1962 subsequent requests received by the original server. The 1963 NFS4ERR_MOVED error is returned for all operations except GETATTR. 1965 Draft Specification NFS version 4 Protocol December 1999 1967 Upon receiving the NFS4ERR_MOVED error, the client will obtain the 1968 value of the fs_locations attribute. The client will then use the 1969 contents of the attribute to redirect its requests to the specified 1970 server. To facilitate the use of GETATTR operations such as PUTFH 1971 must also be accepted by the server for the migrated file system's 1972 filehandles. Note that if the server returns NFS4ERR_MOVED, the 1973 server MUST support the fs_locations attribute. 1975 If the client requests more attributes than fs_locations, the server 1976 may return fs_locations only. This is to be expected since the 1977 server has migrated the file system and may not have a method of 1978 obtaining additional attribute data. 1980 The server implementor needs to be careful in developing a migration 1981 solution. The server must consider all of the state information 1982 clients may have outstanding at the server. This includes but is not 1983 limited to locking/share state, delegation state, and asynchronous 1984 file writes which are represented by WRITE and COMMIT verifiers. The 1985 server should strive to minimize the impact on its clients during and 1986 after the migration process. 1988 6.3. Interpretation of the fs_locations Attribute 1990 The fs_location attribute is structured in the following way: 1992 struct fs_location { 1993 utf8string server<>; 1994 pathname4 rootpath; 1995 }; 1997 struct fs_locations { 1998 pathname4 fs_root; 1999 fs_location locations<>; 2000 }; 2002 The fs_location struct is used to represent the location of a file 2003 system by providing a server name and the path to the root of the 2004 file system. For a multi-homed server or a set of servers that use 2005 the same rootpath, an array of server names may be provided. An 2006 entry in the server array is an UTF8 string and represents one of a 2007 traditional DNS host name, IPv4 address, or IPv6 address. It is not 2008 a requirement that all servers that share the same rootpath be listed 2009 in one fs_location struct. The array of server names is provided for 2010 convenience. Servers that share the same rootpath may also be listed 2011 in separate fs_location entries in the fs_locations attribute. 2013 The fs_locations struct and attribute then contains an array of 2015 Draft Specification NFS version 4 Protocol December 1999 2017 locations. Since the namespace of each server may be constructed 2018 differently, the "fs_root" field is provided. The path represented 2019 by fs_root represents the location of the file system in the server's 2020 namespace. Therefore, the fs_root path is only associated with the 2021 server from which the fs_locations attribute was obtained. The 2022 fs_root path is meant to aid the client in locating the file system 2023 at the various servers listed. 2025 As an example, there is a replicated file system located at two 2026 servers (servA and servB). At servA the file system is located at 2027 path "/a/b/c". At servB the file system is located at path "/x/y/z". 2028 In this example the client accesses the file system first at servA 2029 with a multi-component lookup path of "/a/b/c/d". Since the client 2030 used a multi-component lookup to obtain the filehandle at "/a/b/c/d", 2031 it is unaware that the file system's root is located in servA's 2032 namespace at "/a/b/c". When the client switches to servB, it will 2033 need to determine that the directory it first referenced at servA is 2034 now represented by the path "/x/y/z/d" on servB. To facilitate this, 2035 the fs_locations attribute provided by servA would have a fs_root 2036 value of "/a/b/c" and two entries in fs_location. One entry in 2037 fs_location will be for itself (servA) and the other will be for 2038 servB with a path of "/x/y/z". With this information, the client is 2039 able to substitute "/x/y/z" for the "/a/b/c" at the beginning of its 2040 access path and construct "/x/y/z/d" to use for the new server. 2042 6.4. Filehandle Recovery for Migration or Replication 2044 Filehandles for file systems that are replicated or migrated have the 2045 same semantics as for file systems that are not replicated or 2046 migrated. For example, if a file system has persistent filehandles 2047 and it is migrated to another server, the filehandle values for the 2048 file system will be valid at the new server. 2050 The same is true for a file system which is made up of volatile 2051 filehandles. In fact, in this case the client should expect that the 2052 new server will return NFS4ERR_FHEXPIRED when old filehandles are 2053 presented; the client will need to recover the filehandles 2054 appropriately. 2056 Draft Specification NFS version 4 Protocol December 1999 2058 7. NFS Server Namespace 2060 7.1. Server Exports 2062 On a UNIX server the name space describes all the files reachable by 2063 pathnames under the root directory or "/". On a Windows NT server 2064 the name space constitutes all the files on disks named by mapped 2065 disk letters. NFS server administrators rarely make the entire 2066 server's file system name space available to NFS clients. More often 2067 portions of the name space are made available via an "export" 2068 feature. In previous versions of the NFS protocol, the root 2069 filehandle for each export is obtained through the MOUNT protocol; 2070 the client sends a string that identifies the export of name space 2071 and the server returns the root filehandle for it. The MOUNT 2072 protocol supports an EXPORTS procedure that will enumerate the 2073 server's exports. 2075 7.2. Browsing Exports 2077 The NFS version 4 protocol provides a root filehandle that clients 2078 can use to obtain filehandles for these exports via a multi-component 2079 LOOKUP. A common user experience is to use a graphical user 2080 interface (perhaps a file "Open" dialog window) to find a file via 2081 progressive browsing through a directory tree. The client must be 2082 able to move from one export to another export via single-component, 2083 progressive LOOKUP operations. 2085 This style of browsing is not well supported by the NFS version 2 and 2086 3 protocols. The client expects all LOOKUP operations to remain 2087 within a single server file system. For example, the device 2088 attribute will not change. This prevents a client from taking name 2089 space paths that span exports. 2091 An automounter on the client can obtain a snapshot of the server's 2092 name space using the EXPORTS procedure of the MOUNT protocol. If it 2093 understands the server's pathname syntax, it can create an image of 2094 the server's name space on the client. The parts of the name space 2095 that are not exported by the server are filled in with a "pseudo file 2096 system" that allows the user to browse from one mounted file system 2097 to another. There is a drawback to this representation of the 2098 server's name space on the client: it is static. If the server 2099 administrator adds a new export the client will be unaware of it. 2101 Draft Specification NFS version 4 Protocol December 1999 2103 7.3. Server Pseudo File System 2105 NFS version 4 servers avoid this name space inconsistency by 2106 presenting all the exports within the framework of a single server 2107 name space. An NFS version 4 client uses LOOKUP and READDIR 2108 operations to browse seamlessly from one export to another. Portions 2109 of the server name space that are not exported are bridged via a 2110 "pseudo file system" that provides a view of exported directories 2111 only. A pseudo file system has a unique fsid and behaves like a 2112 normal, read only file system. 2114 Based on the construction of the server's name space, it is possible 2115 that multiple pseudo filesystems may exist. For example, 2117 /a pseudo file system 2118 /a/b real file system 2119 /a/b/c pseudo file system 2120 /a/b/c/d real file system 2122 Each of the pseudo file systems are consider separate entities and 2123 therefore will have a unique fsid. 2125 7.4. Multiple Roots 2127 The DOS and Windows operating environments are sometimes described as 2128 having "multiple roots". File systems are commonly represented as 2129 disk letters. MacOS represents file systems as top level names. NFS 2130 version 4 servers for these platforms can construct a pseudo file 2131 system above these root names so that disk letters or volume names 2132 are simply directory names in the pseudo root. 2134 7.5. Filehandle Volatility 2136 The nature of the server's pseudo file system is that it is a logical 2137 representation of file system(s) available from the server. 2138 Therefore, the pseudo file system is most likely constructed 2139 dynamically when the server is first instantiated. It is expected 2140 that the pseudo file system may not have an on disk counterpart from 2141 which persistent filehandles could be constructed. Even though it is 2142 preferable that the server provide persistent filehandles for the 2143 pseudo file system, the NFS client should expect that pseudo file 2144 system filehandles are volatile. This can be confirmed by checking 2145 the associated "persistent_fh" attribute for those filehandles in 2146 question. If the filehandles are volatile, the NFS client must be 2147 prepared to recover a filehandle value (i.e. with a v4 multi- 2148 component LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 2150 Draft Specification NFS version 4 Protocol December 1999 2152 7.6. Exported Root 2154 If the server's root file system is exported, it might be easy to 2155 conclude that a pseudo-file system is not needed. This would be 2156 wrong. Assume the following file systems on a server: 2158 / disk1 (exported) 2159 /a disk2 (not exported) 2160 /a/b disk3 (exported) 2162 Because disk2 is not exported, disk3 cannot be reached with simple 2163 LOOKUPs. The server must bridge the gap with a pseudo-file system. 2165 7.7. Mount Point Crossing 2167 The server file system environment may be constructed in such a way 2168 that one file system contains a directory which is 'covered' or 2169 mounted upon by a second file system. For example: 2171 /a/b (file system 1) 2172 /a/b/c/d (file system 2) 2174 The pseudo file system for this server may be constructed to look 2175 like: 2177 / (place holder/not exported) 2178 /a/b (file system 1) 2179 /a/b/c/d (file system 2) 2181 It is the server's responsibility to present the pseudo file system 2182 that is complete to the client. If the client sends a lookup request 2183 for the path "/a/b/c/d", the server's response is the filehandle of 2184 the file system "/a/b/c/d". In previous versions of the NFS 2185 protocol, the server would respond with the directory "/a/b/d/d" 2186 within the file system "/a/b". 2188 The NFS client will be able to determine if it crosses a server mount 2189 point by a change in the value of the "fsid" attribute. 2191 7.8. Security Policy and Namespace Presentation 2193 The application of the server's security policy needs to be carefully 2194 considered by the implementor. One may choose to limit the 2195 viewability of portions of the pseudo file system based on the 2196 server's perception of the client's ability to authenticate itself 2197 properly. However with the support of multiple security mechanisms 2199 Draft Specification NFS version 4 Protocol December 1999 2201 and the ability to negotiate the appropriate use of these mechanisms, 2202 the server is unable to properly determine if a client will be able 2203 to authenticate itself. If, based on its policies, the server 2204 chooses to limit the contents of the pseudo file system, the server 2205 may effectively hide file systems from a client that may otherwise 2206 have legitimate access. 2208 Draft Specification NFS version 4 Protocol December 1999 2210 8. File Locking 2212 Integrating locking into the NFS protocol necessarily causes it to be 2213 state-full. With the invasive nature of "share" file locks it 2214 becomes substantially more dependent on state than the traditional 2215 combination of NFS and NLM [XNFS]. There are three components to 2216 making this state manageable: 2218 o Clear division between client and server 2220 o Ability to reliably detect inconsistency in state between client 2221 and server 2223 o Simple and robust recovery mechanisms 2225 In this model, the server owns the state information. The client 2226 communicates its view of this state to the server as needed. The 2227 client is also able to detect inconsistent state before modifying a 2228 file. 2230 To support Win32 "share" locks it is necessary to atomically OPEN or 2231 CREATE files. Having a separate share/unshare operation will not 2232 allow correct implementation of the Win32 OpenFile API. In order to 2233 correctly implement share semantics, the previous NFS protocol 2234 mechanisms used when a file is opened or created (LOOKUP, CREATE, 2235 ACCESS) need to be replaced. The NFS version 4 protocol has an OPEN 2236 operation that subsumes the functionality of LOOKUP, CREATE, and 2237 ACCESS. However, because many operations require a filehandle, the 2238 traditional LOOKUP is preserved to map a file name to filehandle 2239 without establishing state on the server. The policy of granting 2240 access or modifying files is managed by the server based on the 2241 client's state. It is believed that these mechanisms can implement 2242 policy ranging from advisory only locking to full mandatory locking. 2243 While ACCESS is just a subset of OPEN, the ACCESS operation is 2244 maintained as a lighter weight mechanism. 2246 8.1. Definitions 2248 Lock The term "lock" will be used to refer to both record 2249 (byte-range) locks as well as file (share) locks unless 2250 specifically stated otherwise. 2252 Client The term "client" is used to indicate the entity that 2253 maintains a set of locks on behalf of one or more 2254 applications. The client is responsible for crash or 2255 failure recovery for those locks it manages. Multiple 2257 Draft Specification NFS version 4 Protocol December 1999 2259 clients may share the same transport and multiple clients 2260 may exist on the same network node. 2262 Clientid A 64-bit quantity returned by a server that uniquely 2263 corresponds to a client supplied Verifier and ID. 2265 Lease An interval of time defined by the server for which the 2266 client is irrevokeably granted a lock. At the end of a 2267 lease period the lock may be revoked if the lease has not 2268 been extended. The lock must be revoked if a conflicting 2269 lock has been granted after the lease interval. All leases 2270 granted by a server have the same fixed interval. 2272 Stateid A 64-bit quantity returned by a server that uniquely 2273 defines the locking state granted by the server for a 2274 specific lock owner for a specific file. A stateid 2275 composed of all bits 0 or all bits 1 has special meaning 2276 and are reserved values. 2278 Verifier A 32-bit quantity generated by the client that the server 2279 can use to determine if the client has restarted and lost 2280 all previous lock state. 2282 8.2. Locking 2284 It is assumed that manipulating a lock is rare when compared to READ 2285 and WRITE operations. It is also assumed that crashes and network 2286 partitions are relatively rare. Therefore it is important that the 2287 READ and WRITE operations have a light weight mechanism to indicate 2288 if they possess a held lock. A lock request contains the heavy 2289 weight information required to establish a lock and uniquely define 2290 the lock owner. 2292 The following sections describe the transition from the heavy weight 2293 information to the eventual stateid used for most client and server 2294 locking and lease interactions. 2296 8.2.1. Client ID 2298 For each LOCK request, the client must identify itself to the server. 2299 This is done in such a way as to allow for correct lock 2300 identification and crash recovery. Client identification is 2301 accomplished with two values. 2303 o A verifier that is used to detect client reboots. 2305 o A variable length opaque array to uniquely define a client. 2307 Draft Specification NFS version 4 Protocol December 1999 2309 For an operating system this may be a fully qualified host 2310 name or IP address. For a user level NFS client it may 2311 additionally contain a process id or other unique sequence. 2313 The data structure for the Client ID would then appear as: 2315 struct nfs_client_id { 2316 opaque verifier[4]; 2317 opaque id<>; 2318 } 2320 It is possible through the mis-configuration of a client or the 2321 existence of a rogue client that two clients end up using the same 2322 nfs_client_id. This situation is avoided by "negotiating" the 2323 nfs_client_id between client and server with the use of the 2324 SETCLIENTID and SETCLIENTID_CONFIRM operations. The following 2325 describes the two scenarios of negotiation. 2327 1 Client has never connected to the server 2329 In this case the client generates an nfs_client_id and 2330 unless another client has the same nfs_client_id.id field, 2331 the server accepts the request. The server also records the 2332 principal (or principal to uid mapping) from the credential 2333 in the RPC request that contains the nfs_client_id 2334 negotiation request (SETCLIENTID operation). 2336 Two clients might still use the same nfs_client_id.id due 2337 to perhaps configuration error. For example, a High 2338 Availability configuration where the nfs_client_id.id is 2339 derived from the ethernet controller address and both 2340 systems have the same address. In this case, the result is 2341 a switched union that returns in addition to 2342 NFS4ERR_CLID_INUSE, the network address (the rpcbind netid 2343 and universal address) of the client that is using the id. 2345 2 Client is re-connecting to the server after a client reboot 2347 In this case, the client still generates an nfs_client_id 2348 but the nfs_client_id.id field will be the same as the 2349 nfs_client_id.id generated prior to reboot. If the server 2350 finds that the principal/uid is equal to the previously 2351 "registered" nfs_client_id.id, then locks associated with 2352 the old nfs_client_id are immediately released. If the 2353 principal/uid is not equal, then this is a rogue client and 2354 the request is returned in error. For more discussion of 2355 crash recovery semantics, see the section on "Crash 2357 Draft Specification NFS version 4 Protocol December 1999 2359 Recovery" 2361 To mitigate retransmission of the SETCLIENTID operation, 2362 the client has the choice to request of the server a 2363 confirmation step. In the SETCLIENTID request, the client 2364 would specify that it wants to confirm the clientid. The 2365 server would return a confirmation cookie that is then 2366 returned to the server in the SETCLIENTID_CONFIRM 2367 operation. Once the server receives the confirmation from 2368 the client, the locking state for the client is released. 2370 In both cases, upon success, NFS4_OK is returned. To help reduce the 2371 amount of data transferred on OPEN and LOCK, the server will also 2372 return a unique 64-bit clientid value that is a shorthand reference 2373 to the nfs_client_id values presented by the client. From this point 2374 forward, the client will use the clientid to refer to itself. 2376 The clientid assigned by the server should be chosen so that it will 2377 not conflict with a clientid previously assigned by the server. This 2378 applies across server restarts or reboots. When a clientid is 2379 presented to a server and that clientid is not recognized, as would 2380 happen after a server reboot, the server will reject the request with 2381 the error NFS4ERR_STALE_CLIENTID. When this happens, the client must 2382 obtain a new clientid by use of the SETCLIENTID operation and then 2383 proceed to any other necessary recovery for the server reboot case 2384 (See the section "Server Failure and Recovery"). 2386 The client must also employ the SETCLIENTID operation when it 2387 receives a NFS4ERR_STALE_STATEID error using a stateid derived from 2388 its current clientid since this also indicates a server reboot which 2389 has invalidated the existing clientid (see the next section 2390 "nfs_lockowner and stateid Definition" for details). 2392 8.2.2. nfs_lockowner and stateid Definition 2394 When requesting a lock, the client must present to the server the 2395 clientid and an identifier for the owner of the requested lock. 2396 These two fields are referred to as the nfs_lockowner and the 2397 definition of those fields are: 2399 o A clientid returned by the server as part of the clients use of 2400 the SETCLIENTID operation. 2402 o A variable length opaque array used to uniquely define the owner 2403 of a lock managed by the client. 2405 This may be a thread id, process id, or other unique value. 2407 Draft Specification NFS version 4 Protocol December 1999 2409 When the server grants the lock it responds with a unique 64-bit 2410 stateid. The stateid is used as a shorthand reference to the 2411 nfs_lockowner, since the server will be maintaining the 2412 correspondence between them. 2414 The server is free to form the stateid in any manner that it chooses 2415 as long as it is able to recognize invalid and out-of-date stateids. 2416 This requirement includes those stateids generated by earlier 2417 instances of the server. From this, the client can be properly 2418 notified of a server restart. This notification will occur when the 2419 client presents a stateid to the server from a previous 2420 instantiation. 2422 The server must be able to distinguish the following situations and 2423 return the error as specified: 2425 o The stateid was generated by an earlier server instance (i.e. 2426 before a server reboot). The error NFS4ERR_STALE_STATEID should 2427 be returned. 2429 o The stateid was generated by the current server instance but the 2430 stateid no longer designates the current locking state for the 2431 lockowner-file pair in question (i.e. one or more locking 2432 operations has occurred). The error NFS4ERR_OLD_STATEID should 2433 be returned. 2435 This error condition will occur when the client issues a locking 2436 request which changes a stateid while an I/O request that uses 2437 that stateid is outstanding. 2439 o The stateid was generated by the current server instance but the 2440 stateid does not designate a locking state for any active 2441 lockowner-file pair. The error NFS4ERR_BAD_STATEID should be 2442 returned. 2444 This error condition will occur when there has been a logic 2445 error on the part of the client or server. This should not 2446 happen. 2448 One mechanism that may be used to satisfy these requirements is for 2449 the server to divide stateids into three fields: 2451 o A server verifier which uniquely designates a particular server 2452 instantiation. 2454 o An index into a table of locking-state structures. 2456 o A sequence value which is incremented for each stateid that is 2458 Draft Specification NFS version 4 Protocol December 1999 2460 associated with the same index into the locking-state table. 2462 By matching the incoming stateid and its field values with the state 2463 held at the server, the server is able to easily determine if a 2464 stateid is valid for its current instantiation and state. If the 2465 stateid is not valid, the appropriate error can be supplied to the 2466 client. 2468 8.2.3. Use of the stateid 2470 All READ and WRITE operations contain a stateid. If the 2471 nfs_lockowner performs a READ or WRITE on a range of bytes within a 2472 locked range, the stateid returned by the server must be used to 2473 indicate the appropriate lock (record or share) is held. If no state 2474 is established by the client, either record lock or share lock, a 2475 stateid of all bits 0 is used. If no conflicting locks are held on 2476 the file, the server may service the READ or WRITE operation. If a 2477 conflict with an explicit lock occurs, an error is returned for the 2478 operation (NFS4ERR_LOCKED). This allows "mandatory locking" to be 2479 implemented. 2481 A stateid of all bits 1 allows READ operations to bypass locking 2482 checks at the server. However, WRITE operations with stateid with 2483 bits all 1 do not bypass file locking requirements. 2485 An explicit lock may not be granted while a READ or WRITE operation 2486 with conflicting implicit locking is being performed. 2488 The byte range of a lock is indivisible. A range may be locked or 2489 unlocked between read and write but may not have subranges unlocked 2490 or changed between read and write. These are the semantics provided 2491 by the Win32 environment but only a subset of the semantics provided 2492 by Unix environment. It is expected that Unix clients can more 2493 easily simulate modifying subranges than Win32 servers adding this 2494 feature. 2496 8.2.4. Sequencing of Lock Requests 2498 Locking is different than most NFS operations as it requires "at- 2499 most-one" semantics that are not provided by ONCRPC. In the face of 2500 retransmission or reordering, lock or unlock requests must have a 2501 well defined and consistent behavior. To accomplish this, each lock 2502 request contains a sequence number that is a consecutively increasing 2503 integer. Different nfs_lockowners have different sequences. The 2504 server maintains the last sequence number (L) received and the 2506 Draft Specification NFS version 4 Protocol December 1999 2508 response that was returned. 2510 If a request with a previous sequence number (r < L) is received, it 2511 is rejected with the return of error NFS4ERR_BAD_SEQID. Given a 2512 properly-functioning client, the response to (r) must have been 2513 received before the last request (L) was sent. If a duplicate of 2514 last request (r == L) is received, the stored response is returned. 2515 If a request beyond the next sequence (r == L + 2) is received, it is 2516 rejected with the return of error NFS4ERR_BAD_SEQID. Sequence 2517 history is reinitialized whenever the client verifier changes. 2519 8.3. Blocking Locks 2521 Some clients require the support of blocking locks. The NFS version 2522 4 protocol must not rely on a callback mechanism and therefore is 2523 unable to notify a client when a lock has been granted. Clients have 2524 no choice but to continually poll for the lock. This presents a 2525 fairness problem. Two new lock types are added, READW and WRITEW, 2526 and are used to indicate to the server that the client is requesting 2527 a blocking lock. The server should maintain an ordered list of 2528 pending blocking locks. When the conflicting lock is released, the 2529 server may wait the lease period for the first client to re-request 2530 the lock. After the lease period expires the next waiting client 2531 request is allowed the lock. Clients are required to poll at an 2532 interval sufficiently small that it is likely to acquire the lock in 2533 a timely manner. The server is not required to maintain a list of 2534 pending blocked locks as it is used to increase fairness and not 2535 correct operation. Because of the unordered nature of crash 2536 recovery, storing of lock state to stable storage would be required 2537 to guarantee ordered granting of blocking locks. 2539 8.4. Lease Renewal 2541 The purpose of a lease is to allow a server to remove stale locks 2542 that are held by a client that has crashed or is otherwise 2543 unreachable. It is not a mechanism for cache consistency and lease 2544 renewals may not be denied if the lease interval has not expired. 2546 The following events cause implicit renewal of all of the leases for 2547 a given client (i.e. all those sharing a given clientid). Each of 2548 these is a positive indication that the client is still active and 2549 that the associated state held at the server, for the client, is 2550 still valid. 2552 o An OPEN with a valid clientid. 2554 Draft Specification NFS version 4 Protocol December 1999 2556 o Any operation made with a valid stateid (CLOSE, DELEGRETURN, 2557 LOCK, LOCKU, OPEN, OPEN_CONFIRM, READ, RENEW, SETATTR, WRITE). 2558 This does not include the special stateids of all bits 0 or all 2559 bits 1. 2561 Note that if the client had restarted or rebooted, the 2562 client would not be making these requests without issuing 2563 the SETCLIENTID operation. The use of the SETCLIENTID (and 2564 optional SETCLIENTID_CONFIRM) operation(s) notifies the 2565 server to drop the locking state associated with the 2566 client. 2568 If the server has rebooted, the stateids 2569 (NFS4ERR_STALE_STATEID error) or the clientid 2570 (NFS4ERR_STALE_CLIENTID error) will not be valid hence 2571 preventing spurious renewals. 2573 This approach allows for low overhead lease renewal which scales 2574 well. In the typical case no extra RPC calls are required for lease 2575 renewal and in the worst case one RPC is required every lease period 2576 (i.e. a RENEW operation). The number of locks held by the client is 2577 not a factor since all state for the client is involved with the 2578 lease renewal action. 2580 Since all operations that create a new lease also renew existing 2581 leases, the server must maintain a common lease expiration time for 2582 all valid leases for a given client. This lease time can then be 2583 easily updated upon implicit lease renewal actions. 2585 8.5. Crash Recovery 2587 The important requirement in crash recovery is that both the client 2588 and the server know when the other has failed. Additionally, it is 2589 required that a client sees a consistent view of data across server 2590 restarts or reboots. All READ and WRITE operations that may have 2591 been queued within the client or network buffers must wait until the 2592 client has successfully recovered the locks protecting the READ and 2593 WRITE operations. 2595 8.5.1. Client Failure and Recovery 2597 In the event that a client fails, the server may recover the client's 2598 locks when the associated leases have expired. Conflicting locks 2599 from another client may only be granted after this lease expiration. 2600 If the client is able to restart or reinitialize within the lease 2601 period the client may be forced to wait the remainder of the lease 2603 Draft Specification NFS version 4 Protocol December 1999 2605 period before obtaining new locks. 2607 To minimize client delay upon restart, lock requests are associated 2608 with an instance of the client by a client supplied verifier. This 2609 verifier is part of the initial SETCLIENTID call made by the client. 2610 The server returns a clientid as a result of the SETCLIENTID 2611 operation. The clientid in combination with an opaque owner field is 2612 then used by the client to identify the lock owner. 2614 Since the verifier will be changed by the client upon each 2615 initialization, the server can compare a new verifier to the verifier 2616 associated with currently held locks and determine that they do not 2617 match. This signifies the client's new instantiation and subsequent 2618 loss of locking state. As a result, the server is free to release 2619 all locks held which are associated with the old clientid which was 2620 derived from the old verifier. 2622 For secure environments, a change in the verifier must only cause the 2623 release of locks associated with the authenticated requester. This 2624 is required to prevent a rogue entity from freeing otherwise valid 2625 locks. 2627 Note that the verifier must have the same uniqueness properties of 2628 the verify for the COMMIT operation. 2630 8.5.2. Server Failure and Recovery 2632 If the server loses locking state (usually as a result of a restart 2633 or reboot), it must allow clients time to discover this fact and re- 2634 establish the lost locking state. The client must be able to re- 2635 establish the locking state without having the server deny valid 2636 requests because the server has granted conflicting access to another 2637 client. Likewise, if there is the possibility that clients have not 2638 yet re-established their locking state for a file, the server must 2639 disallow READ and WRITE operations for that file. The duration of 2640 this recovery period is equal to the duration of the lease period. 2642 A client can determine that server failure (and thus loss of locking 2643 state) has occurred, when it receives one of two errors. The 2644 NFS4ERR_STALE_STATEID error indicates a stateid invalidated by a 2645 reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a 2646 clientid invalidated by reboot or restart. When either of these are 2647 received, the client must establish a new clientid (See the section 2648 "Client ID") and re-establish the locking state as discussed below. 2650 The period of special handling of locking and READs and WRITEs, equal 2651 in duration to the lease period, is referred to as the "grace 2653 Draft Specification NFS version 4 Protocol December 1999 2655 period". During the grace period, clients recover locks and the 2656 associated state by reclaim-type locking requests (i.e. LOCK requests 2657 with reclaim set to true and OPEN operations with a claim type of 2658 CLAIM_PREVIOUS). During the grace period, the server must reject 2659 READ and WRITE operations and non-reclaim locking requests (i.e. 2660 other LOCK and OPEN operations) with an error of NFS4ERR_GRACE. 2662 If the server can reliably determine that granting a non-reclaim 2663 request will not conflict with reclamation of locks by other clients, 2664 the NFS4ERR_GRACE error does not have to be returned and the non- 2665 reclaim client request can be serviced. For the server to be able to 2666 service READ and WRITE operations during the grace period, it must 2667 again be able to guarantee that no possible conflict could arise 2668 between an impending reclaim locking request and the READ or WRITE 2669 operation. If the server is unable to offer that guarantee, the 2670 NFS4ERR_GRACE error must be returned to the client. 2672 For a server to provide simple, valid handling during the grace 2673 period, the easiest method is to simply reject all non-reclaim 2674 locking requests and READ and WRITE operations by returning the 2675 NFS4ERR_GRACE error. However, a server may keep information about 2676 granted locks in stable storage. With this information, the server 2677 could determine if a regular lock or READ or WRITE operation can be 2678 safely processed. 2680 For example, if a count of locks on a given file is available in 2681 stable storage, the server can track reclaimed locks for the file and 2682 when all reclaims have been processed, non-reclaim locking requests 2683 may be processed. This way the server can ensure that non-reclaim 2684 locking requests will not conflict with potential reclaim requests. 2685 With respect to I/O requests if the server is able to determine that 2686 there are no outstanding reclaim requests for a file by information 2687 from stable storage of another similar mechanism, the processing of 2688 I/O requests could proceed normally for the file. 2690 To reiterate, for the server that allows non-reclaim lock and I/O 2691 requests to be processed during the grace period, it MUST determine 2692 that no lock subsequently reclaimed will be rejected and that no lock 2693 subsequently reclaimed would have prevented any I/O operation 2694 processed during the grace period. 2696 Clients should be prepared for the return of NFS4ERR_GRACE errors for 2697 non-reclaim lock and I/O requests. In this case the client should 2698 employ a backoff and retry mechanism for the request. Timeout 2699 periods should be chosen to avoid overwhelming a server. The client 2700 must account for the server that is able to perform I/O and non- 2701 reclaim locking requests within the grace period as well as those 2702 that can not. 2704 Draft Specification NFS version 4 Protocol December 1999 2706 A reclaim-type locking request outside the server's grace period can 2707 only succeed if the server can guarantee that no conflicting lock or 2708 I/O request has been granted since reboot or restart. 2710 8.5.3. Network Partitions and Recovery 2712 If the duration of a network partition is greater than the lease 2713 period provided by the server, the server will have not received a 2714 lease renewal from the client. If this occurs, the server may free 2715 all locks held for the client. As a result, all stateids held by the 2716 client will become invalid or stale. Once the client is able to 2717 reach the server after such a network partition, all I/O submitted by 2718 the client with the now invalid stateids will fail with the server 2719 returning the error NFS4ERR_EXPIRED. Once this error is received, 2720 the client will suitably notify the application that held the lock. 2722 As a courtesy to the client or optimization, the server may continue 2723 to hold locks on behalf of a client for which recent communication 2724 has extended beyond the lease period. If the server receives a lock 2725 or I/O request that conflicts with one of these courtesy locks, the 2726 server must free the courtesy lock and grant the new request. 2728 In the event of a network partition with a duration extending beyond 2729 the expiration of a client's leases, the server MUST employ a method 2730 of recording this fact in its stable storage. Conflicting locks 2731 requests from another client may be serviced after the lease 2732 expiration. There are various scenarios involving server failure 2733 after such an event that require the storage of these lease 2734 expirations or network partitions. One scenario is as follows: 2736 A client holds a lock at the server and encounters a 2737 network partition and is unable to renew the associated 2738 lease. A second client obtains a conflicting lock and then 2739 frees the lock. After the unlock request by the second 2740 client, the server reboots or reinitializes. Once the 2741 server recovers, the network partition heals and the 2742 original client attempts to reclaim the original lock. 2744 In this scenario and without any state information, the server will 2745 allow the reclaim and the client will be in an inconsistent state 2746 because the server or the client has no knowledge of the conflicting 2747 lock. 2749 The server may choose to store this lease expiration or network 2750 partitioning state in a way that will only identify the client as a 2751 whole. Note that this may potentially lead to lock reclaims being 2752 denied unnecessarily because of a mix of conflicting and non- 2754 Draft Specification NFS version 4 Protocol December 1999 2756 conflicting locks. The server may also choose to store information 2757 about each lock that has an expired lease with an associated 2758 conflicting lock. The choice of the amount and type of state 2759 information that is stored is left to the implementor. In any case, 2760 the server must have enough state information to enable correct 2761 recovery from multiple partitions and multiple server failures. 2763 8.6. Server Revocation of Locks 2765 At any point, the server can revoke locks held by a client and the 2766 client must be prepared for this event. When the client detects that 2767 its locks have been or may have been revoked, the client is 2768 responsible for validating the state information between itself and 2769 the server. Validating locking state for the client means that it 2770 must verify or reclaim state for each lock currently held. 2772 The first instance of lock revocation is upon server reboot or re- 2773 initialization. In this instance the client will receive an error or 2774 NFS4ERR_GRACE and the client will proceed with normal crash recovery 2775 as described in the previous section. 2777 The second lock revocation event can occur as a result of 2778 administrative intervention within the lease period. While this is 2779 considered a rare event, it is possible that the server's 2780 administrator has decided to release or revoke a particular lock held 2781 by the client. As a result of revocation, the client will receive an 2782 error of NFS4ERR_EXPIRED and the error is received within the lease 2783 period for the lock. In this instance the client may assume that 2784 only the nfs_lockowner's locks have been lost. The client notifies 2785 the lock holder appropriately. The client may not assume the lease 2786 period has been renewed as a result of failed operation. 2788 The third lock revocation event is the inability to renew the lease 2789 period. While this is considered a rare or unusual event, the client 2790 must be prepared to recover. Both the server and client will be able 2791 to detect the failure to renew the lease and are capable of 2792 recovering without data corruption. For the server, it tracks the 2793 last renewal event serviced for the client and knows when the lease 2794 will expire. Similarly, the client must track operations which will 2795 renew the lease period. Using the time that each such request was 2796 sent and the time that the corresponding reply was received, the 2797 client should bound the time that the corresponding renewal could 2798 have occurred on the server and thus determine if it is possible that 2799 a lease period expiration could have occurred. 2801 When the client determines the lease period may have expired, the 2802 client must mark all locks held for the associated lease as 2804 Draft Specification NFS version 4 Protocol December 1999 2806 "unvalidated". This means the client has been unable to re-establish 2807 or confirm the appropriate lock state with the server. As described 2808 in the previous section on crash recovery, there are scenarios in 2809 which the server may grant conflicting locks after the lease period 2810 has expired for a client. When it is possible that the lease period 2811 has expired, the client must validate each lock currently held to 2812 ensure that a conflicting lock has not been granted. The client may 2813 accomplish this task by issuing an I/O request, either a pending I/O 2814 or a zero-length read, specifying the stateid associated with the 2815 lock in question. If the response to the request is success, the 2816 client has validated all of the locks governed by that stateid and 2817 re-established the appropriate state between itself and the server. 2818 If the I/O request is not successful, then one or more of the locks 2819 associated with the stateid was revoked by the server and the client 2820 must notify the owner. 2822 8.7. Share Reservations 2824 A share reservation is a mechanism to control access to a file. It 2825 is a separate and independent mechanism from record locking. When a 2826 client opens a file, it issues an OPEN operation to the server 2827 specifying the type of access required (READ, WRITE, or BOTH) and the 2828 type of access to deny others (deny NONE, READ, WRITE, or BOTH). If 2829 the OPEN fails the client will fail the applications open request. 2831 Pseudo-code definition of the semantics: 2833 if ((request.access & file_state.deny)) || 2834 (request.deny & file_state.access)) 2835 return (NFS4ERR_DENIED) 2837 8.8. OPEN/CLOSE Operations 2839 To provide correct share semantics, a client MUST use the OPEN 2840 operation to obtain the initial filehandle and indicate the desired 2841 access and what if any access to deny. Even if the client intends to 2842 use a stateid of all 0's or all 1's, it must still obtain the 2843 filehandle for the regular file with the OPEN operation so the 2844 appropriate share semantics can be applied. For clients that do not 2845 have a deny mode built into their open programming interfaces, deny 2846 equal to NONE should be used. 2848 The OPEN operation with the CREATE flag, also subsumes the CREATE 2849 operation for regular files as used in previous versions of the NFS 2851 Draft Specification NFS version 4 Protocol December 1999 2853 protocol. This allows a create with a share to be done atomicly. 2855 The CLOSE operation removes all share locks held by the nfs_lockowner 2856 on that file. If record locks are held, the client SHOULD release 2857 all locks before issuing a CLOSE. The server MAY free all 2858 outstanding locks on CLOSE but some servers may not support the CLOSE 2859 of a file that still has record locks held. The server MUST return 2860 failure if any locks would exist after the CLOSE. 2862 The LOOKUP operation is preserved and will return a filehandle 2863 without establishing any lock state on the server. Without a valid 2864 stateid, the server will assume the client has the least access. For 2865 example, a file opened with deny READ/WRITE cannot be accessed using 2866 a filehandle obtained through LOOKUP because it would not have a 2867 valid stateid (i.e. using a stateid of all bits 0 or all bits 1). 2869 8.9. Short and Long Leases 2871 When determining the time period for the server lease, the usual 2872 lease tradeoffs apply. Short leases are good for fast server 2873 recovery at a cost of increased RENEW or READ (with zero length) 2874 requests. Longer leases are certainly kinder and gentler to large 2875 internet servers trying to handle a very large numbers of clients. 2876 The number of RENEW requests drop in direct proportion to the lease 2877 time. The disadvantages of long leases are slower recovery after 2878 server failure (server must wait for leases to expire and grace 2879 period before granting new lock requests) and increased file 2880 contention (if client fails to transmit an unlock request then server 2881 must wait for lease expiration before granting new locks). 2883 Long leases are usable if the server is able to store lease state in 2884 non-volatile memory. Upon recovery, the server can reconstruct the 2885 lease state from its non-volatile memory and continue operation with 2886 its clients and therefore long leases are not an issue. 2888 8.10. Clocks and Calculating Lease Expiration 2890 To avoid the need for synchronized clocks, lease times are granted by 2891 the server as a time delta. However, there is a requirement that the 2892 client and server clocks do not drift excessively over the duration 2893 of the lock. There is also the issue of propagation delay across the 2894 network which could easily be several hundred milliseconds as well as 2895 the possibility that requests will be lost and need to be 2896 retransmitted. 2898 To take propagation delay into account, the client should subtract it 2900 Draft Specification NFS version 4 Protocol December 1999 2902 from lease times (e.g. if the client estimates the one-way 2903 propagation delay as 200 msec, then it can assume that the lease is 2904 already 200 msec old when it gets it). In addition, it will take 2905 another 200 msec to get a response back to the server. So the client 2906 must send a lock renewal or write data back to the server 400 msec 2907 before the lease would expire. 2909 Draft Specification NFS version 4 Protocol December 1999 2911 9. Client-Side Caching 2913 Client-side caching of data, of file attributes, and of file names is 2914 essential to providing good performance with the NFS protocol. 2915 Providing distributed cache coherence is a difficult problem and 2916 previous versions of the NFS protocol have not attempted it. 2917 Instead, several NFS client implementation techniques have been used 2918 to reduce the problems that a lack of coherence poses for users. 2919 These techniques have not been clearly defined by earlier protocol 2920 specifications and it is often unclear what is valid or invalid 2921 client behavior. 2923 The NFS version 4 protocol uses many techniques similar to those that 2924 have been used in previous protocol versions. The NFS version 4 2925 protocol does not provide distributed cache coherence. However, it 2926 defines a more limited set of caching guarantees to allow locks and 2927 share reservations to be used without destructive interference from 2928 client side caching. 2930 In addition, the NFS version 4 protocol introduces a delegation 2931 mechanism which allows many decisions normally made by the server to 2932 be made locally by clients. This mechanism provides efficient 2933 support of the common cases where sharing is infrequent or where 2934 sharing is read-only. 2936 9.1. Performance Challenges for Client-Side Caching 2938 Caching techniques used in previous versions of the NFS protocol have 2939 been successful in providing good performance. However, several 2940 scalability challenges can arise when those techniques are used with 2941 very large numbers of clients. This is particularly true when 2942 clients are geographically distributed which classically increases 2943 the latency for cache revalidation requests. 2945 The previous versions of the NFS protocol repeat their file data 2946 cache validation requests at the time the file is opened. This 2947 behavior can have serious performance drawbacks. A common case is 2948 one in which a file is only accessed by a single client. Therefore, 2949 sharing is infrequent. 2951 In this case, repeated reference to the server to find that no 2952 conflicts exist is expensive. A better option with regards to 2953 performance is to allow a client that repeatedly opens a file to do 2954 so without reference to the server. This is done until potentially 2955 conflicting operations from another client actually occur. 2957 A similar situation arises in connection with file locking. Sending 2959 Draft Specification NFS version 4 Protocol December 1999 2961 file lock and unlock requests to the server as well as the read and 2962 write requests necessary to make data caching consistent with the 2963 locking semantics (see the section "Data Caching and File Locking") 2964 can severely limit performance. When locking is used to provide 2965 protection against infrequent conflicts, a large penalty is incurred. 2966 This penalty may discourage the use of file locking by applications. 2968 The NFS version 4 protocol provides more aggressive caching 2969 strategies with the following design goals: 2971 o Compatibility with a large range of server semantics. 2973 o Provide the same caching benefits as previous versions of the 2974 NFS protocol when unable to provide the more aggressive model. 2976 o Requirements for aggressive caching are organized so that a 2977 large portion of the benefit can be obtained even when not all 2978 of the requirements can be met. 2980 The appropriate requirements for the server are discussed in later 2981 sections in which specific forms of caching are covered. (see the 2982 section "Open Delegation"). 2984 9.2. Delegation and Callbacks 2986 Recallable delegation of server responsibilities for a file to a 2987 client improves performance by avoiding repeated requests to the 2988 server in the absence of inter-client conflict. With the use of a 2989 "callback" RPC from server to client, a server recalls delegated 2990 responsibilities when another client engages in sharing of a 2991 delegated file. 2993 A delegation is passed from the server to the client, specifying the 2994 object of the delegation and the type of delegation. There are 2995 different types of delegations but each type contains a stateid to be 2996 used to represent the delegation when performing operations that 2997 depend on the delegation. This stateid is similar to those 2998 associated with locks and share reservations but differs in that the 2999 stateid for a delegation is associated with a clientid and may be 3000 used on behalf of all the nfs_lockowners for the given client. A 3001 delegation is made to the client as a whole and not to any specific 3002 process or thread of control within it. 3004 Because callback RPCs may not work in all environments (due to 3005 firewalls, for example), correct protocol operation does not depend 3006 on them. Preliminary testing of callback functionality by means of a 3008 Draft Specification NFS version 4 Protocol December 1999 3010 CB_NULL procedure determines whether callbacks can be supported. The 3011 CB_NULL procedure checks the continuity of the callback path. A 3012 server makes a preliminary assessment of callback availability to a 3013 given client and avoids delegating responsibilities until it has 3014 determined that callbacks are supported. Because the granting of a 3015 delegation is always conditional upon the absence of conflicting 3016 access, clients must not assume that a delegation will be granted and 3017 they must always be prepared for denial. 3019 Once granted, a delegation behaves in most ways like a lock. There 3020 is an associated lease that is subject to renewal together with all 3021 of the other leases held by that client. 3023 Unlike locks, an operation by a second client to a delegated file 3024 will cause the server to recall a delegation through a callback. 3026 On recall, the client holding the delegation must flush modified 3027 state (such as modified data) to the server and return the 3028 delegation. The conflicting request will not receive a response 3029 until the recall is complete. The recall is considered complete when 3030 the client returns the delegation or the server times out on the 3031 recall and revokes the delegation as a result of the time out. 3032 Following the resolution of the recall, the server has the 3033 information necessary to grant or deny the second client's request. 3035 At the time the client receives a delegation recall, it may have 3036 substantial state that needs to be flushed to the server. Therefore, 3037 the server should allow sufficient time for the recall RPC to 3038 complete since it involves atypical actions. If the server is able 3039 to determine that the client is diligently flushing state to the 3040 server as a result of the recall, the server may extend the usual 3041 time allowed for a recall. However, the time allowed for recall 3042 completion should not be unbounded. 3044 An example of this is when responsibility to mediate opens on a given 3045 file is delegated to a client (see the section "Open Delegation"). 3046 The server will not know what opens are in effect on the client. 3047 Without this knowledge the server will be unable to determine if the 3048 access and deny state for the file allows any particular open until 3049 the delegation for the file has been returned. 3051 A client failure or a network partition can result in failure to 3052 respond to a recall callback. In this case, the server will revoke 3053 the delegation which in turn will render useless any modified state 3054 still on the client. 3056 Draft Specification NFS version 4 Protocol December 1999 3058 9.2.1. Delegation Recovery 3060 There are three situations that delegation recovery must deal with: 3062 o Client reboot or restart 3064 o Server reboot or restart 3066 o Network partition (full or callback-only) 3068 In the event the client reboots or restarts, the failure to renew 3069 leases will result in the revocation of record locks and share 3070 reservations. Delegations, however, may treated a bit differently. 3072 There will be situations in which delegations will need to be 3073 reestablished after a client reboots or restarts. The reason for 3074 this is the client may have file data stored locally and this data 3075 was associated with the previously held delegations. The client will 3076 need to reestablish the appropriate file state on the server. 3078 To allow for this type of client recovery, the server may extend the 3079 period for delegation recovery beyond the typical lease expiration 3080 period. This implies that requests from other clients that conflict 3081 with these delegations will need to wait. This behavior is 3082 consistent with the normal recall process may take significant time 3083 because of the client's need to flush state to the server. This 3084 longer interval would increase the window for clients to reboot and 3085 consult stable storage so that the delegations can be reclaimed. For 3086 open delegations, such delegations are reclaimed using OPEN with a 3087 claim type of CLAIM_DELEGATE_PREV. (see the sections on "Data 3088 Caching and Revocation" and "Operation 18: OPEN" for discussion of 3089 open delegation and the details of OPEN respectively). 3091 When the server reboots or restarts, delegations are reclaimed (using 3092 the OPEN operation with CLAIM_DELEGATE_PREV) in a similar fashion to 3093 record locks and share reservations. However, there is a slight 3094 semantic difference. In the normal case if the server decides that a 3095 delegation should not be granted, it performs the requested action 3096 (e.g. OPEN) without granting any delegation. For reclaim, the server 3097 grants the delegation but a special designation is applied so that 3098 the client treats the delegation as having been granted but recalled 3099 by the server. Because of this, the client has the duty to write all 3100 modified state to the server and then return the delegation. This 3101 process of handling delegation reclaim reconciles three principles of 3102 the NFS Version 4 protocol: 3104 Draft Specification NFS version 4 Protocol December 1999 3106 o Upon reclaim, a client reporting resources assigned to it by an 3107 earlier server instance must be granted those resources. 3109 o The server has unquestionable authority to determine whether 3110 delegations are to be granted and, once granted, whether they 3111 are to be continued. 3113 o The use of callbacks is not to be depended upon until the client 3114 has proven its ability to receive them. 3116 When a network partition occurs, delegations are subject to freeing 3117 by the server when the lease renewal period expires. This is similar 3118 to the behavior for locks and share reservations. For delegations, 3119 however, the server may extend the period in which conflicting 3120 requests are held off. Eventually the occurrence of a conflicting 3121 request from another client will cause revocation of the delegation. 3122 A loss of the callback path (e.g. by later network configuration 3123 change) will have the same effect. A recall request will fail and 3124 revocation of the delegation will result. 3126 A client normally finds out about revocation of a delegation when it 3127 uses a stateid associated with a delegation and receives the error 3128 NFS4ERR_EXPIRED. It also may find out about delegation revocation 3129 after a client reboot when it attempts to reclaim a delegation and 3130 receives that same error. Note that in the case of a revoked write 3131 open delegation, there are issues because data may have been modified 3132 by the client whose delegation is revoked and separately by other 3133 clients. See the section "Revocation Recovery for Write Open 3134 Delegation" for a discussion of such issues. Note also that when 3135 delegations are revoked, information about the revoked delegation 3136 will be written by the server to stable storage (as described in the 3137 section "Crash Recovery"). This is done to deal with the case in 3138 which a server reboots after revoking a delegation but before the 3139 client holding the revoked delegation is notified about the 3140 revocation. 3142 9.3. Data Caching 3144 When applications share access to a set of files they need to be 3145 implemented so as to take account of the possibility of conflicting 3146 access by another application. This is true whether the applications 3147 in question execute on different clients or reside on the same 3148 client. 3150 Share reservations and record locks are the facilities the NFS 3151 version 4 protocol provides to allow applications to coordinate 3152 access by providing mutual exclusion facilities. The NFS version 4 3154 Draft Specification NFS version 4 Protocol December 1999 3156 protocol's data caching must be implemented such that it does not 3157 invalidate the assumptions that those using these facilities depend 3158 upon. 3160 9.3.1. Data Caching and OPENs 3162 In order to avoid invalidating the sharing assumptions that 3163 applications rely on, NFS version 4 clients should not provide cached 3164 data to applications or modify it on behalf of an application when it 3165 would not be valid to obtain or modify that same data via a READ or 3166 WRITE operation. 3168 Furthermore, in the absence of open delegation (see the section "Open 3169 Delegation") two additional rules apply. Note that these rules are 3170 obeyed in practice by many NFS version 2 and version 3 clients. 3172 o First, cached data present on a client must be revalidated after 3173 doing an OPEN. This is to ensure that the data for the OPENed 3174 file is still correctly reflected in the client's cache. This 3175 validation must be done at least when the client's OPEN 3176 operation includes DENY=WRITE or BOTH thus terminating a period 3177 in which other clients may have had the opportunity to open the 3178 file with WRITE access. Clients may choose to do the 3179 revalidation more often (i.e. at OPENs specifying DENY=NONE) to 3180 parallel the NFS version 3 protocol's practice for the benefit 3181 of users assuming this degree of cache revalidation. 3183 o Second, modified data must be flushed to the server before 3184 closing a file OPENed for write. This is complementary to the 3185 first rule. If the data is not flushed at CLOSE, the 3186 revalidation done after client OPENs as file is unable to 3187 achieve its purpose. The other aspect to flushing the data 3188 before close is that the data must be committed to stable 3189 storage before the CLOSE operation is requested by the client. 3190 In the case of a server reboot or restart and a CLOSEd file, it 3191 may not be possible to retransmit the data to be written to the 3192 file. Hence, this requirement. 3194 9.3.2. Data Caching and File Locking 3196 For those applications that choose to use file locking instead of 3197 share reservations to exclude inconsistent file access, there is an 3198 analogous set of constraints that apply to client side data caching. 3199 These rules are effective only if the file locking is used in a way 3200 that matches in an equivalent way the actual READ and WRITE 3201 operations executed. This is opposed to file locking that is based 3203 Draft Specification NFS version 4 Protocol December 1999 3205 on pure convention. For example, it is possible to manipulate a 2 3206 megabyte file by dividing the file into two 1 (one) megabyte regions 3207 and protecting access to the two regions by file locks on bytes 0 3208 (zero) and 1 (one). A lock for write on byte 0 (zero) of the file 3209 would represent the right to do READ and WRITE operations on the 3210 first region. A lock for write on byte 1 (one) of the file would 3211 represent the right to do READ and WRITE operations on the second 3212 region. As long as all applications manipulating the file obey this 3213 convention, they will work on a local file system. However, they may 3214 not work with the NFS version 4 protocol unless clients refrain from 3215 data caching. 3217 The rules for data caching in the file locking environment are: 3219 o First, when a client obtains a file lock for a particular 3220 region, the data cache corresponding to that region (if any 3221 cache data exists) must be revalidated. If the change attribute 3222 indicates that the file may have been updated since the cached 3223 data was obtained, the client must flush or invalidate the 3224 cached data for the newly locked region. A client might choose 3225 to invalidate all of non-modified cached data that it has for 3226 the file but the only requirement for correct operation is to 3227 invalidate all of the data in the newly locked region. 3229 o Second, before releasing a write lock for a region, all modified 3230 data for that region must be flushed to the server. The 3231 modified data must also be written to stable storage. 3233 Note that flushing data to the server and the invalidation of cached 3234 data must reflect the actual byte ranges locked or unlocked. 3235 Rounding these up or down to reflect client cache block boundaries 3236 will cause problems if not carefully done. For example, writing a 3237 modified block when only half of that block is within an area being 3238 unlocked may cause invalid modification to the region outside the 3239 unlocked area. This, in turn, may be part of a region locked by 3240 another client. Clients can avoid this situation by synchronously 3241 performing portions of write operations that overlap that portion 3242 (initial or final) that is not a full block. Similarly, invalidating 3243 a locked area which is not an integral number of full buffer blocks 3244 would require the client to read one or two partial blocks from the 3245 server if the revalidation procedure shows that the data which the 3246 client possesses may not be valid. 3248 The data that is written to the server as a pre-requisite of the 3249 unlocking of a region must be written to stable storage. The client 3250 may accomplish this with either synchronous writes or following 3251 asynchronous writes by the COMMIT operation. This is required 3252 because retransmission of the modified data after a server reboot 3254 Draft Specification NFS version 4 Protocol December 1999 3256 might conflict with a lock held by another client. 3258 A client implementation may choose to accommodate applications which 3259 use record locking in non-standard ways (e.g. using a record lock as 3260 a global semaphore) by flushing to the server more data upon an LOCKU 3261 than is covered by the locked range. This may include modified data 3262 within files other than the one for which the unlocks are being done. 3263 In such cases, the client must not interfere with applications whose 3264 READs and WRITEs are being done only within the bounds of record 3265 locks which the application holds. For example, an application locks 3266 a single byte of a file and proceeds to write that single byte. A 3267 client that chose to handle a LOCKU by flushing all modified data to 3268 the server could validly write that single byte in response to an 3269 unrelated unlock. However, it would not be valid to write the entire 3270 block in which that single written byte was located since it includes 3271 an area that is not locked and might be locked by another client. 3272 Client implementations can avoid this problem by dividing files with 3273 modified data into those for which all modifications are done to 3274 areas covered by an appropriate record lock and those for which there 3275 are modifications not covered by a record lock. Any writes done for 3276 the former class of files must not include areas not locked and thus 3277 not modified on the client. 3279 9.3.3. Data Caching and Mandatory File Locking 3281 Client side data caching needs to respect mandatory file locking when 3282 it is in effect. The presence of mandatory file locking for a given 3283 file is indicated in the result flags for an OPEN. When mandatory 3284 locking is in effect for a file, the client must check for an 3285 appropriate file lock for data being read or written. If a lock 3286 exists for the range being read or written, the client may satisfy 3287 the request using the client's validated cache. If an appropriate 3288 file lock is not held for the range of the read or write, the read or 3289 write request must not be satisfied by the client's cache and the 3290 request sent to the server for processing. When a read or write 3291 request partially overlaps a locked region, the request should be 3292 subdivided into multiple pieces with each region (locked or not) 3293 treated appropriately. 3295 9.3.4. Data Caching and File Identity 3297 When clients cache data, the file data needs to organized according 3298 to the file system object to which the data belongs. For NFS version 3299 3 clients, the typical practice has been to assume for the purpose of 3300 caching that distinct filehandles represent distinct file system 3301 objects. The client then has the choice to organize and maintain the 3303 Draft Specification NFS version 4 Protocol December 1999 3305 data cache on this basis. 3307 In the NFS version 4 protocol, there is now the possibility to have 3308 significant deviations from a "one filehandle per object" model 3309 because a filehandle may be constructed on the basis of the object's 3310 pathname. Therefore, clients need a reliable method to determine if 3311 two filehandles designate the same file system object. If clients 3312 simply assume that all distinct filehandles denote distinct objects 3313 and proceed to do data caching on this basis, caching inconsistencies 3314 would arise between the distinct client side objects which mapped to 3315 the same server side object. 3317 By providing a method to differentiate filehandles, the NFS version 4 3318 protocol alleviates a potential functional digression in comparison 3319 to the NFS version 3 protocol. Without this method, caching 3320 inconsistencies within the same client could occur and this has not 3321 been present in previous versions of the NFS protocol. Note that it 3322 is possible to have such inconsistencies with applications executing 3323 on multiple clients but that is not the issue being address here. 3325 For the purposes of data caching, the following steps allow an NFS 3326 version 4 client to determine whether two distinct filehandles denote 3327 the same server side object: 3329 o If GETATTR directed to two filehandles have different values of 3330 the fsid attribute, then the filehandles represent distinct 3331 objects. 3333 o If GETATTR for any file with an fsid that matches the fsid of 3334 the two filehandles in question returns a unique_handles 3335 attribute with a value of TRUE, then the two objects are 3336 distinct. 3338 o If GETATTR directed to the two filehandles does not return the 3339 fileid attribute for one or both of the handles, then the it 3340 cannot be determined whether the two objects are the same. 3341 Therefore, operations which depend on that knowledge (e.g. 3342 client side data caching) cannot be done reliably. 3344 o If GETATTR directed to the two filehandles returns different 3345 values for the fileid attribute, then they are distinct objects. 3347 o Otherwise they are the same object. 3349 Draft Specification NFS version 4 Protocol December 1999 3351 9.4. Open Delegation 3353 When a file is being OPENed, the server may delegate further handling 3354 of opens and closes for that file to the opening client. Any such 3355 delegation is recallable, since the circumstances that allowed for 3356 the delegation are subject to change. In particular, the server may 3357 receive a conflicting OPEN from another client, the server must 3358 recall the delegation before deciding whether the OPEN from the other 3359 client may be granted. Granting a delegation request is up to the 3360 server and it may deny all such requests. The following is a typical 3361 set of conditions that servers might use in deciding whether OPEN 3362 should be delegated: 3364 o The client must be able to respond to the server's callback 3365 requests. The server will use the CB_NULL procedure for a test 3366 of callback ability. 3368 o The client must have responded properly to previous recalls. 3370 o There must be no current open conflicting with the requested 3371 delegation. 3373 o There should be no current delegation that conflicts with the 3374 delegation being requested. 3376 o The probability of future conflicting open requests should be 3377 low based on the recent history of the file. 3379 o The existence of any server specific semantics of OPEN/CLOSE 3380 that would make the required handling incompatible with the 3381 prescribed handling that the delegated client would apply (see 3382 below). 3384 There are two types of open delegations, read and write. A read open 3385 delegation allows a client to handle, on its own, requests to open a 3386 file for reading that do not deny read access to others. Multiple 3387 read open delegations may be outstanding simultaneously and do not 3388 conflict. A write open delegation allows the client to handle, on 3389 its own, all opens. Only one write open delegation may exist for a 3390 given file at a given time and it is inconsistent with any read open 3391 delegations. 3393 When a client has a read open delegation, it may not make any changes 3394 to the contents or attributes of the file but it is assured that no 3395 other client may do so. When a client has a write open delegation, 3396 it may modify the file data since no other client will be accessing 3397 the file's data. The client holding a write delegation may only 3398 affect file attributes which are intimately connected with the file 3400 Draft Specification NFS version 4 Protocol December 1999 3402 data: object_size, time_modify. 3404 When a client has an open delegation, it does not send OPENs or 3405 CLOSEs to the server but updates the appropriate status internally. 3406 For a read open delegation, opens that cannot be handled locally 3407 (opens for write or that deny read access) must be sent to the 3408 server. 3410 When an open delegation is requested and granted, the response to the 3411 OPEN contains an open delegation structure which specifies the 3412 following: 3414 o the type of delegation (read or write) 3416 o space limitation information to control flushing of data on 3417 close (write open delegation only, see the section "Open 3418 Delegation and Data Caching") 3420 o an nfsace4 specifying read and write permissions 3422 o a stateid to represent the delegation for READ and WRITE 3424 The stateid is separate and distinct from the stateid for the OPEN 3425 proper. The standard stateid, unlike the delegation stateid, is 3426 associated with a particular nfs_lockowner and will continue to be 3427 valid after the delegation is recalled and the file remains open. 3429 When a request internal to the client is made to open a file and open 3430 delegation is in effect, it will be accepted or rejected solely on 3431 the basis of the following conditions. Any requirement for other 3432 checks to be made by the delegate should result in open delegation 3433 being denied so that the checks can be made by the server itself. 3435 o The access and deny bits for the request and the file as 3436 described in the section "Share Reservations". 3438 o The read and write permissions as determined below. 3440 The nfsace4 passed with delegation can be used to avoid frequent 3441 ACCESS calls. The permission check should be as follows: 3443 o If the nfsace4 indicates that the open may be done, then it 3444 should be granted without reference to the server. 3446 o If the nfsace4 indicates that the open may not be done, then an 3447 ACCESS request must be sent to the server to obtain the 3448 definitive answer. 3450 Draft Specification NFS version 4 Protocol December 1999 3452 The server may return an nfsace4 that is more restrictive than the 3453 actual ACL of the file. This includes an nfsace4 that specifies 3454 denial of all access. Note that some common practices such as 3455 mapping the traditional user "root" to the user "nobody" may make it 3456 incorrect to return the actual ACL of the file in the delegation 3457 response. 3459 The use of delegation together with various other forms of caching 3460 creates the possibility that no server authentication will ever be 3461 performed for a given user since all of the user's requests might be 3462 satisfied locally. Where the client is depending on the server for 3463 authentication, the client should be sure authentication occurs for 3464 each user by use of the ACCESS operation. This should be the case 3465 even if an ACCESS operation would not required otherwise. As 3466 mentioned before, the server may enforce frequent authentication by 3467 returning an nfsace4 denying all access with every open delegation. 3469 9.4.1. Open Delegation and Data Caching 3471 OPEN delegation allows much of the message overhead associated with 3472 the opening and closing files to be eliminated. An open when an open 3473 delegation is in effect does not require that a validation message be 3474 sent to the server. The continued endurance of the "read open 3475 delegation" provides a guarantee that no OPEN for write and thus no 3476 write has occurred. Similarly, when closing a file opened for write 3477 and if write open delegation is in effect, the data written does not 3478 have to be flushed to the server until the open delegation is 3479 recalled. The continued endurance of the open delegation provides a 3480 guarantee that no open and thus no read or write has been done by 3481 another client. 3483 For the purposes of open delegation, READs and WRITEs done without an 3484 OPEN are treated as the functional equivalent of a corresponding type 3485 of OPEN. This refers to the READs and WRITEs that use the special 3486 stateids consisting of all zero bits or all one bits. Therefore, 3487 READs or WRITEs with a special stateid done by another client will 3488 force the server to recall a write open delegation. A WRITE with a 3489 special stateid done by another client will force a recall of read 3490 open delegations. 3492 With delegations, a client is able to avoid writing data to the 3493 server when the CLOSE of a file is serviced. The CLOSE operation is 3494 the usual point at which the client is notified of a lack of stable 3495 storage for the modified file data generated by the application. At 3496 the CLOSE, file data is written to the server and through normal 3497 accounting the server is able to determine if the available file 3498 system space for the data has been exceeded (i.e. server returns 3500 Draft Specification NFS version 4 Protocol December 1999 3502 NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. 3503 The introduction of delegations requires that a alternative method be 3504 in place for the same type of communication to occur between client 3505 and server. 3507 In the delegation response, the server provides either the limit of 3508 the size of the file or the number of modified blocks and associated 3509 block size. The server must ensure that the client will be able to 3510 flush data to the server of a size equal to that provided in the 3511 original delegation. The server must make this assurance for all 3512 outstanding delegations. Therefore, the server must be careful in 3513 its management of available space for new or modified data taking 3514 into account available file system space and any applicable quotas. 3515 The server can recall delegations as a result of managing the 3516 available file system space. The client should abide by the server's 3517 state space limits for delegations. If the client exceeds the stated 3518 limits for the delegation, the server's behavior is undefined. 3520 Based on server conditions, quotas or available file system space, 3521 the server my grant write open delegations with very restrictive 3522 space limitations. The limitations may be defined in a way that will 3523 always force modified data to be flushed to the server on close. 3525 With respect to authentication, flushing modified data to the server 3526 after a CLOSE has occurred may be problematic. For example, the user 3527 of the application may have logged off of the client and unexpired 3528 authentication credentials may not be present. In this case, the 3529 client may need to take special care to ensure that local unexpired 3530 credentials will in fact be available. This may be accomplished by 3531 tracking the expiration time of credentials and flushing data well in 3532 advance of their expiration or by making private copies of 3533 credentials to assure their availability when needed. 3535 9.4.2. Open Delegation and File Locks 3537 When a client holds a write open delegation, lock operations are 3538 performed locally. This includes those required for mandatory file 3539 locking. This can be done since the delegation implies that there 3540 can be no conflicting locks. Similarly, all of the revalidations 3541 that would normally be associated with obtaining locks and the 3542 flushing of data associated with the releasing of locks need not be 3543 done. 3545 9.4.3. Recall of Open Delegation 3547 The following events necessitate recall of an open delegation: 3549 Draft Specification NFS version 4 Protocol December 1999 3551 o Potentially conflicting OPEN request (or READ/WRITE done with 3552 "special" stateid) 3554 o SETATTR issued by another client 3556 o REMOVE request for the file 3558 o RENAME request for the file as either source or target of the 3559 RENAME 3561 Whether a RENAME of a directory in the path leading to the file 3562 results in recall of an open delegation depends on the semantics of 3563 the server file system. If that file system denies such RENAMEs when 3564 a file is open, the recall must be performed to determine whether the 3565 file in question is, in fact, open. 3567 In addition to the situations above, the server may choose to recall 3568 open delegations at any time if resource constraints make it 3569 advisable to do so. Clients should always be prepared for the 3570 possibility of recall. 3572 The server needs to employ special handling for a GETATTR where the 3573 target is a file that has a write open delegation in effect. In this 3574 case, the client holding the delegation needs to be interrogated. 3575 The server will use a CB_GETATTR callback, if the GETATTR attribute 3576 bits include any of the attributes that a write open delegate may 3577 modify (object_size, time_modify, change). 3579 When a client receives a recall for an open delegation, it needs to 3580 update state on the server before returning the delegation. These 3581 same updates must be done whenever a client chooses to return a 3582 delegation voluntarily. The following items of state need to be 3583 dealt with: 3585 o If the file associated with the delegation is no longer open and 3586 no previous CLOSE operation has been sent to the server, a CLOSE 3587 operation must be sent to the server. 3589 o If file has other open references at the client, then OPEN 3590 operations must be sent to the server. The appropriate stateids 3591 will be provided by the server for subsequent use by the client 3592 since the delegation stateid will not longer be valid. These 3593 OPEN requests are done with the claim type of 3594 CLAIM_DELEGATE_CUR. This will allow the presentation of the 3595 delegation stateid so that the client can establish the 3596 appropriate rights to perform the OPEN. (see the section 3597 "Operation 18: OPEN" for details.) 3599 Draft Specification NFS version 4 Protocol December 1999 3601 o If there are granted file locks, the corresponding LOCK 3602 operations need to be performed. This applies to the write open 3603 delegation case only. 3605 o For a write open delegation at the time of recall if the file is 3606 not open for write, all modified data for the file must be 3607 flushed to the server. If the delegation had not existed, the 3608 client would have done this data flush before the CLOSE 3609 operation. 3611 o With the write open delegation in place, it is possible that the 3612 file was truncated during the duration of the delegation. For 3613 example, the truncation could have occurred as a result of an 3614 OPEN UNCHECKED with a object_size attribute value of zero. 3615 Therefore, if a truncation of the file has occurred and this 3616 operation has not been propagated to the server, the truncation 3617 must occur before any modified data is written to the server. 3619 o Any modified data for the file needs to be flushed to the the 3620 server. 3622 In the case of write open delegation, file locking imposes some 3623 additional requirements. The flushing of any modified data in any 3624 region for which a write lock was released while the write open 3625 delegation was in effect is what is required to precisely maintain 3626 the associated invariant. However, because the write open delegation 3627 implies no other locking by other clients, a simpler implementation 3628 is to flush all modified data for the file (as described just above) 3629 if any write lock has been released while the write open delegation 3630 was in effect. 3632 9.4.4. Delegation Revocation 3634 At the point a delegation is revoked, if there are associated opens 3635 on the client, the applications holding these opens need to be 3636 notified. This notification usually occurs by returning errors for 3637 READ/WRITE operations or when a close is attempted for the open file. 3639 If no opens exist for the file at the point the delegation is 3640 revoked, then notification of the revocation is unnecessary. 3641 However, if there is modified data present at the client for the 3642 file, the user of the application should be notified. Unfortunately, 3643 it may not be possible to notify the user since active applications 3644 may not be present at the client. See the section "Revocation 3645 Recovery for Write Open Delegation" for additional details. 3647 Draft Specification NFS version 4 Protocol December 1999 3649 9.5. Data Caching and Revocation 3651 When locks and delegations are revoked, the assumptions upon which 3652 successful caching depend are no longer guaranteed. The owner of the 3653 locks or share reservations which have been revoked needs to be 3654 notified. This notification includes applications with a file open 3655 that has a corresponding delegation which has been revoked. Cached 3656 data associated with the revocation must be removed from the client. 3657 In the case of modified data existing in the client's cache, that 3658 data must be removed from the client without it being written to the 3659 server. 3661 Notification to a lock owner will in many cases consist of simply 3662 returning an error on the next and all subsequent READs/WRITEs to the 3663 open file or on the close. Where the methods available to a client 3664 to make such notification impossible because errors for certain 3665 operations may not be returned, more drastic action such as signals 3666 or process termination may be appropriate. The justification for 3667 this is that an invariant for which an application depends on may be 3668 violated. Depending on how errors are typically treated for the 3669 client operating environment, further levels of notification 3670 including logging, console messages, and GUI pop-ups may be in 3671 appropriate. 3673 9.5.1. Revocation Recovery for Write Open Delegation 3675 Revocation recovery for a write open delegation poses the special 3676 issue of modified data in the client cache while the file is not 3677 open. In this situation, any client which does not flush modified 3678 data to the server on each close must ensure that the user receives 3679 appropriate notification of the failure as a result of the 3680 revocation. Since such situations may require human action to 3681 correct problems, notification schemes in which the appropriate user 3682 or administrator is notified may be necessary. Logging and console 3683 messages are typical examples. 3685 If there is modified data on the client, it must not be flushed 3686 normally to the server. A client may attempt to provide a copy of 3687 the file data as modified during the delegation under a different 3688 name in the file system name space to ease recovery. Unless the 3689 client can determine that the file has not modified by any other 3690 client, this technique must be limited to situations in which a 3691 client has a complete cached copy of the file in question. Use of 3692 such a technique may be limited to files under a certain size or may 3693 only be used when sufficient disk space is guaranteed to be available 3694 within the target file system and when the client has sufficient 3695 buffering resources to keep the cached copy available until it is 3697 Draft Specification NFS version 4 Protocol December 1999 3699 properly stored to the target file system. 3701 9.6. Attribute Caching 3703 The attributes discussed in this section do not include named 3704 attributes. Individual named attributes are analogous to files and 3705 caching of the data for these needs to be handled just as data 3706 caching is for ordinary files. Similarly, LOOKUP results from an 3707 OPENATTR directory are to be cached on the same basis as any other 3708 pathnames and similarly for directory contents. 3710 Clients may cache file attributes obtained from the server and use 3711 them to avoid subsequent GETATTR requests. Such caching is write 3712 through in that modification to file attributes is always done by 3713 means of requests to the server and should not be done locally and 3714 cached. The exception to this are modifications to attributes that 3715 are intimately connected with data caching. Therefore, extending a 3716 file by writing data to the local data cache is reflected immediately 3717 in the object_size as seen on the client without this change being 3718 immediately reflected on the server. Normally such changes are not 3719 propagated directly to the server but when the modified data is 3720 flushed to the server, analogous attribute changes are made on the 3721 server. When open delegation is in effect, the modified attributes 3722 may be returned to the server in the response to a CB_RECALL call. 3724 The result of local caching of attributes is that the attribute 3725 caches maintained on individual clients will not be coherent. Changes 3726 made in one order on the server may be seen in a different order on 3727 one client and in a third order on a different client. 3729 The typical file system application programming interfaces do not 3730 provide means to atomically modify or interrogate attributes for 3731 multiple files at the same time. The following rules provide an 3732 environment where the potential incoherences mentioned above can be 3733 reasonably managed. These rules are derived from the practice of 3734 previous NFS protocols. 3736 o All attributes for a given file (per-fsid attributes excepted) 3737 are cached as a unit at the client so that no non- 3738 serializability can arise within the context of a single file. 3740 o An upper time boundary is maintained on how long a client cache 3741 entry can be kept without being refreshed from the server. 3743 o When operations are performed that change attributes at the 3744 server, the updated attribute set is requested as part of the 3745 containing RPC. This includes directory operations that update 3747 Draft Specification NFS version 4 Protocol December 1999 3749 attributes indirectly. This is accomplished by following the 3750 modifying operation with a GETATTR operation and then using the 3751 results of the GETATTR to update the client's cached attributes. 3753 Note that if the full set of attributes to be cached is requested by 3754 READDIR, the results can be cached by the client on the same basis as 3755 attributes obtained via GETATTR. 3757 A client may validate its cached version of attributes for a file by 3758 fetching only the change attribute and assuming that if the change 3759 attribute has the same value as it did when the attributes were 3760 cached, then no attributes have changed. The possible exception is 3761 the attribute time_access. 3763 9.7. Name Caching 3765 The results of LOOKUP and READDIR operations may be cached to avoid 3766 the cost of subsequent LOOKUP operations. Just as in the case of 3767 attribute caching inconsistencies may arise among the various client 3768 caches. To mitigate the effects of these inconsistencies and given 3769 the context of typical file system APIs, the following rules should 3770 be followed: 3772 o The results of unsuccessful LOOKUPs should not be cached, unless 3773 they are specifically reverified at the point of use. 3775 o An upper time boundary is maintained on how long a client name 3776 cache entry can be kept without verifying that the entry has not 3777 been made invalid by a directory change operation performed by 3778 another client. 3780 When a client is not making changes to a directory for which there 3781 exist name cache entries, the client needs to periodically fetch 3782 attributes for that directory to ensure that it is not being 3783 modified. After determining that no modification has occurred, the 3784 expiration time for the associated name cache entries may be updated 3785 to be the current time plus the name cache staleness bound. 3787 When a client is making changes to a given directory, it needs to 3788 determine whether there have been changes made to the directory by 3789 other clients. It does this by using the change attribute as 3790 reported before and after the directory operation in the associated 3791 change_info4 value returned for the operation. The server is able to 3792 communicate to the client whether the change_info4 data is provided 3793 atomically with respect to the directory operation. If the change 3794 values are provided atomically, the client is then able to compare 3795 the pre-operation change value with the change value in the client's 3797 Draft Specification NFS version 4 Protocol December 1999 3799 name cache. If the comparison indicates that the directory was 3800 updated by another client, the name cache associated with the 3801 modified directory is purged from the client. If the comparison 3802 indicates no modification, the name cache can be updated on the 3803 client to reflect the directory operation and the associated timeout 3804 extended. The post-operation change value needs to be saved as the 3805 basis for future change_info4 comparisons. 3807 As demonstrated by the scenario above, name caching requires that the 3808 client revalidate name cache data by inspecting the change attribute 3809 of a directory at the point when the name cache item was cached. 3810 This requires that the server update the change attribute for 3811 directories when the contents of the corresponding directory is 3812 modified. For a client to use the change_info4 information 3813 appropriately and correctly, the server must report the pre and post 3814 operation change attribute values atomically. When the server is 3815 unable to report the before and after values atomically with respect 3816 to the directory operation, the server must indicate that fact in the 3817 change_info4 return value. When the information is not atomically 3818 reported, the client should not assume that other clients have not 3819 changed the directory. 3821 9.8. Directory Caching 3823 The results of READDIR operations may be used to avoid subsequent 3824 READDIR operations. Just as in the cases of attribute and name 3825 caching inconsistencies may arise among the various client caches. 3826 To mitigate the effects of these inconsistencies and given the 3827 context of typical file system APIs, the following rules should be 3828 followed: 3830 o Cached READDIR information for a directory which is not obtained 3831 in a single READDIR operation must always be a consistent 3832 snapshot of directory contents. This is determined by using a 3833 GETATTR before the first READDIR and after the last of READDIR 3834 that contributes to the cache. 3836 o An upper time boundary is maintained to indicate the length of 3837 time a directory cache entry is considered valid before the 3838 client must revalidate the cached information. 3840 The revalidation technique parallels that discussed in the case of 3841 name caching. When the client is not changing the directory in 3842 question, checking the change attribute of the directory with GETATTR 3843 is adequate. The lifetime of the cache entry can be extended at 3844 these checkpoints. When a client is modifying the directory, the 3845 client needs to use the change_info4 data to determine whether there 3847 Draft Specification NFS version 4 Protocol December 1999 3849 are other clients modifying the directory. If it is determined that 3850 no other client modifications are occurring, the client may update 3851 its directory cache to reflect its own changes. 3853 As demonstrated previously, directory caching requires that the 3854 client revalidate directory cache data by inspecting the change 3855 attribute of a directory at the point when the directory was cached. 3856 This requires that the server update the change attribute for 3857 directories when the contents of the corresponding directory is 3858 modified. For a client to use the change_info4 information 3859 appropriately and correctly, the server must report the pre and post 3860 operation change attribute values atomically. When the server is 3861 unable to report the before and after values atomically with respect 3862 to the directory operation, the server must indicate that fact in the 3863 change_info4 return value. When the information is not atomically 3864 reported, the client should not assume that other clients have not 3865 changed the directory. 3867 Draft Specification NFS version 4 Protocol December 1999 3869 10. Minor Versioning 3871 To address the requirement of an NFS protocol that can evolve as the 3872 need arises, the NFS version 4 protocol contains the rules and 3873 framework to allow for future minor changes or versioning. 3875 The base assumption with respect to minor versioning is that any 3876 future accepted minor version must follow the IETF process and be 3877 documented in a standards track RFC. Therefore, each minor version 3878 number will correspond to an RFC. Minor version zero of the NFS 3879 version 4 protocol is represented by this RFC. The COMPOUND 3880 procedure will support the encoding of the minor version being 3881 requested by the client. 3883 The following items represent the basic rules for the development of 3884 minor versions. Note that a future minor version may decide to 3885 modify or add to the following rules as part of the minor version 3886 definition. 3888 1 Procedures are not added or deleted 3890 To maintain the general RPC model, NFS version 4 minor versions 3891 will not add or delete procedures from the NFS program. 3893 2 Minor versions may add operations to the COMPOUND procedure. 3895 The addition of operations to the COMPOUND procedure does not 3896 affect the RPC model. 3898 2.1 Minor versions may append attributes to GETATTR4args, bitmap4, 3899 and GETATTR4res. 3901 This allows for the expansion of the attribute model to allow 3902 for future growth or adaptation. 3904 2.2 Minor version X must append any new attributes after the last 3905 documented attribute. 3907 Since attribute results are specified as an opaque array of 3908 per-attribute XDR encoded results, the complexity of adding new 3909 attributes in the midst of the current definitions will be too 3910 burdensome. 3912 Draft Specification NFS version 4 Protocol December 1999 3914 3 Minor versions must not modify the structure of an existing 3915 operation's arguments or results. 3917 Again the complexity of handling multiple structure definitions 3918 for a single operation is too burdensome. New operations should 3919 be added instead of modifying existing structures for a minor 3920 version. 3922 This rule does not preclude the following adaptations in a minor 3923 version. 3925 o adding bits to flag fields such as new attributes to 3926 GETATTR's bitmap4 data type 3928 o adding bits to existing attributes like ACLs that have flag 3929 words 3931 o extending enumerated types (including NFS4ERR_*) with new 3932 values 3934 4 Minor versions may not modify the structure of existing 3935 attributes. 3937 5 Minor versions may not delete operations. 3939 This prevents the potential reuse of a particular operation 3940 "slot" in a future minor version. 3942 6 Minor versions may not delete attributes. 3944 7 Minor versions may not delete flag bits or enumeration values. 3946 8 Minor versions may declare an operation as mandatory to NOT 3947 implement. 3949 Specifying an operation as "mandatory to not implement" is 3950 equivalent to obsoleting an operation. For the client, it means 3951 that the operation should not be sent to the server. For the 3952 server, an NFS error can be returned as opposed to "dropping" 3953 the request as an XDR decode error. This approach allows for 3954 the obsolescence of an operation while maintaining its structure 3955 so that a future minor version can reintroduce the operation. 3957 Draft Specification NFS version 4 Protocol December 1999 3959 8.1 Minor versions may declare attributes mandatory to NOT 3960 implement. 3962 8.2 Minor versions may declare flag bits or enumeration values as 3963 mandatory to NOT implement. 3965 9 Minor versions may downgrade features from mandatory to 3966 recommended, or recommended to optional. 3968 10 Minor versions may upgrade features from optional to recommended 3969 or recommended to mandatory. 3971 11 A client and server that support minor version X must support 3972 minor versions 0 (zero) through X-1 as well. 3974 12 No new features may be introduced as mandatory in a minor 3975 version. 3977 This rule allows for the introduction of new functionality and 3978 forces the use of implementation experience before designating a 3979 feature as mandatory. 3981 13 A client MUST NOT attempt to use a stateid, file handle, or 3982 similar returned object from the COMPOUND procedure with minor 3983 version X for another COMPOUND procedure with minor version Y, 3984 where X != Y. 3986 Draft Specification NFS version 4 Protocol December 1999 3988 11. Internationalization 3990 The primary issue in which NFS needs to deal with 3991 internationalization, or i18n, is with respect to file names and 3992 other strings as used within the protocol. NFS' choice of string 3993 representation must allow reasonable name/string access to clients 3994 which use various languages. The UTF-8 encoding allows for this type 3995 of access and this choice is explained in the following. 3997 11.1. Universal Versus Local Character Sets 3999 [RFC1345] describes a table of 16 bit characters for many different 4000 languages (the bit encodings match Unicode, though of course RFC1345 4001 is somewhat out of date with respect to current Unicode assignments). 4002 Each character from each language has a unique 16 bit value in the 16 4003 bit character set. Thus this table can be thought of as a universal 4004 character set. [RFC1345] then talks about groupings of subsets of the 4005 entire 16 bit character set into "Charset Tables". For example one 4006 might take all the Greek characters from the 16 bit table (which are 4007 are consecutively allocated), and normalize their offsets to a table 4008 that fits in 7 bits. Thus it is determined that "lower case alpha" 4009 is in the same position as "upper case a" in the US-ASCII table, and 4010 "upper case alpha" is in the same position as "lower case a" in the 4011 US-ASCII table. 4013 These normalized subset character sets can be thought of as "local 4014 character sets", suitable for an operating system locale. 4016 Local character sets are not suitable for the NFS protocol. Consider 4017 someone who creates a file with a name in a Swedish character set. If 4018 someone else later goes to access the file with their locale set to 4019 the Swedish language, then there are no problems. But if someone in 4020 say the US-ASCII locale goes to access the file, the file name will 4021 look very different, because the Swedish characters in the 7 bit 4022 table will now be represented in US-ASCII characters on the display. 4023 It would be preferable to give the US-ASCII user a way to display the 4024 file name using Swedish glyphs. In order to do that, the NFS protocol 4025 would have to include the locale with the file name on each operation 4026 to create a file. 4028 But then what of the situation when there is a path name on the 4029 server like: 4031 /component-1/component-2/component-3 4033 Each component could have been created with a different locale. If 4034 one issues CREATE with multi-component path name, and if some of the 4035 leading components already exist, what is to be done with the 4037 Draft Specification NFS version 4 Protocol December 1999 4039 existing components? Is the current locale attribute replaced with 4040 the user's current one? These types of situations quickly become too 4041 complex when there is an alternate solution. 4043 If NFS V4 used a universal 16 bit or 32 bit character set (or a 4044 encoding of a 16 bit or 32 bit character set into octets), then 4045 server and client need not care if the locale of the user accessing 4046 the file is different than the locale of the user who created the 4047 file. The unique 16 bit or 32 bit encoding of the character allows 4048 for determination of what language the character is from and also how 4049 to display that character on the client. The server need not know 4050 what locales are used. 4052 11.2. Overview of Universal Character Set Standards 4054 The previous section makes a case for using a universal character set 4055 in NFS version 4. This section makes the case for using UTF-8 as the 4056 specific universal character set for NFS version 4. 4058 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 4059 Unicode, and UCS-*. There are two standards bodies managing universal 4060 code sets: 4062 o ISO/IEC which has the standard 10646-1 4064 o Unicode which has the Unicode standard 4066 Both standards bodies have pledged to track each other's assignments 4067 of character codes. 4069 The following is a brief analysis of the various standards. 4071 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 4072 multi-octet character set called the Universal Character 4073 Set (UCS), which encompasses most of the world's writing 4074 systems." 4076 UCS-2 a two octet per character encoding that addresses the first 4077 2^16 characters of UCS. Currently there are no UCS 4078 characters beyond that range. 4080 UCS-4 a four octet per character encoding that permits the 4081 encoding of up to 2^31 characters. 4083 Draft Specification NFS version 4 Protocol December 1999 4085 UTF UCS transformation format. 4087 UTF-1 Only historical interest; it has been removed from 10646-1 4089 UTF-7 Encodes the entire "repertoire" of UCS "characters using 4090 only octets with the higher order bit clear". [RFC2152] 4091 describes UTF-7. UTF-7 accomplishes this by reserving one 4092 of the 7bit US-ASCII characters as a "shift" character to 4093 indicate non-US-ASCII characters. 4095 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 4096 characters are encoded as before unchanged. Any octet with 4097 the high bit cleared can only mean a US-ASCII character. 4098 The high bit set means that a UCS character is being 4099 encoded. 4101 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 4102 reserved range in UCS-2. 4104 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 4106 Up to the present time, changes in Unicode and amendments 4107 to ISO/IEC 10646 have tracked each other, so that the 4108 character repertoires and code point assignments have 4109 remained in sync. The relevant standardization committees 4110 have committed to maintain this very useful synchronism. 4112 11.3. Difficulties with UCS-4, UCS-2, Unicode 4114 Adapting existing applications, and file systems to multi-octet 4115 schemes like UCS and Unicode can be difficult. A significant amount 4116 of code has been written to process streams of bytes. Also there are 4117 many existing stored objects described with 7 bit or 8 bit 4118 characters. Doubling or quadrupling the bandwidth and storage 4119 requirements seems like an expensive way to accomplish I18N. 4121 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 4122 enough but, according to [Unicode1], 38,887 Unicode characters are 4123 already assigned. And according to [Unicode2] there are still more 4124 languages that need to be added. 4126 Draft Specification NFS version 4 Protocol December 1999 4128 11.4. UTF-8 and its solutions 4130 UTF-8 solves problems for NFS that exist with the use of UCS and 4131 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 4132 that will be compact for most users. The encoding table from UCS-4 to 4133 UTF-8, as copied from [RFC2279]: 4135 UCS-4 range (hex.) UTF-8 octet sequence (binary) 4136 0000 0000-0000 007F 0xxxxxxx 4137 0000 0080-0000 07FF 110xxxxx 10xxxxxx 4138 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 4140 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 4141 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4142 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4143 10xxxxxx 4145 See [RFC2279] for precise encoding and decoding rules. Note because 4146 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 4147 for the reserved range between D800 and DFFF. 4149 Note that the 16 bit UCS or Unicode characters require no more than 3 4150 octets to encode into UTF-8 4152 Interestingly, UTF-8 has room to handle characters larger than 31 4153 bits, because the leading octet of form: 4155 1111111x 4157 is not defined. If needed, ISO could either use that octet to 4158 indicate a sequence of an encoded 8 octet character, or perhaps use 4159 11111110 to permit the next octet to indicate an even more expandable 4160 character set. 4162 So using UTF-8 to represent character encodings means never having to 4163 run out of room. 4165 Draft Specification NFS version 4 Protocol December 1999 4167 12. Error Definitions 4169 NFS error numbers are assigned to failed operations within a compound 4170 request. A compound request contains a number of NFS operations that 4171 have their results encoded in sequence in a compound reply. The 4172 results of successful operations will consist of an NFS4_OK status 4173 followed by the encoded results of the operation. If an NFS 4174 operation fails, an error status will be entered in the reply and the 4175 compound request will be terminated. 4177 A description of each defined error follows: 4179 NFS4_OK Indicates the operation completed successfully. 4181 NFS4ERR_ACCES Permission denied. The caller does not have the 4182 correct permission to perform the requested 4183 operation. Contrast this with NFS4ERR_PERM, 4184 which restricts itself to owner or privileged 4185 user permission failures. 4187 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 4188 internal consistency checks. 4190 NFS4ERR_BADTYPE An attempt was made to create an object of a 4191 type not supported by the server. 4193 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 4195 NFS4ERR_BAD_SEQID The sequence number in a locking request is 4196 neither the next expected number or the last 4197 number processed. 4199 NFS4ERR_BAD_STATEID A stateid generated by the current server 4200 instance, but which does not designate any 4201 locking state (either current or superseded) 4202 for a current lockowner-file pair, was used. 4204 NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a 4205 client id is already in use by another client. 4207 NFS4ERR_DENIED An attempt to lock a file is denied. Since 4208 this may be a temporary condition, the client 4209 is encouraged to retry the lock request (with 4210 exponential backoff of timeout) until the lock 4211 is accepted. 4213 Draft Specification NFS version 4 Protocol December 1999 4215 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The 4216 user's resource limit on the server has been 4217 exceeded. 4219 NFS4ERR_EXIST File exists. The file specified already exists. 4221 NFS4ERR_EXPIRED A lease has expired that is being used in the 4222 current procedure. 4224 NFS4ERR_FBIG File too large. The operation would have caused 4225 a file to grow beyond the server's limit. 4227 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 4228 expired at the server. 4230 NFS4ERR_GRACE The server is in its recovery or grace period 4231 which should match the lease period of the 4232 server. 4234 NFS4ERR_INVAL Invalid argument or unsupported argument for an 4235 operation. Two examples are attempting a 4236 READLINK on an object other than a symbolic 4237 link or attempting to SETATTR a time field on a 4238 server that does not support this operation. 4240 NFS4ERR_IO I/O error. A hard error (for example, a disk 4241 error) occurred while processing the requested 4242 operation. 4244 NFS4ERR_ISDIR Is a directory. The caller specified a 4245 directory in a non-directory operation. 4247 NFS4ERR_JUKEBOX The server initiated the request, but was not 4248 able to complete it in a timely fashion. The 4249 client should wait and then try the request 4250 with a new RPC transaction ID. For example, 4251 this error should be returned from a server 4252 that supports hierarchical storage and receives 4253 a request to process a file that has been 4254 migrated. In this case, the server should start 4255 the immigration process and respond to client 4256 with this error. 4258 NFS4ERR_LOCKED A read or write operation was attempted on a 4259 locked file. 4261 NFS4ERR_MINOR_VERS_MISMATCH 4262 The server has received a request that 4264 Draft Specification NFS version 4 Protocol December 1999 4266 specifies an unsupported minor version. The 4267 server must return a COMPOUND4res with a zero 4268 length operations result array. 4270 NFS4ERR_MLINK Too many hard links. 4272 NFS4ERR_MOVED The filesystem which contains the current 4273 filehandle object has been relocated or 4274 migrated to another server. The client may 4275 obtain the new filesystem location by obtaining 4276 the "fs_locations" attribute for the current 4277 filehandle. For further discussion, refer to 4278 the section "Filesystem Migration or 4279 Relocation". 4281 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 4283 NFS4ERR_NODEV No such device. 4285 NFS4ERR_NOENT No such file or directory. The file or 4286 directory name specified does not exist. 4288 NFS4ERR_NOFILEHANDLE The logical current file handle value has not 4289 been set properly. This may be a result of a 4290 malformed COMPOUND operation (i.e. no PUTFH or 4291 PUTROOTFH before an operation that requires the 4292 current file handle be set). 4294 NFS4ERR_NOSPC No space left on device. The operation would 4295 have caused the server's file system to exceed 4296 its limit. 4298 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 4299 directory in a directory operation. 4301 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 4302 was not empty. 4304 NFS4ERR_NOTSUPP Operation is not supported. 4306 NFS4ERR_NOT_CONFIRMED The client has not confirmed the use of either 4307 a clientid or an OPEN. 4309 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 4310 during a SETATTR operation. 4312 NFS4ERR_NXIO I/O error. No such device or address. 4314 Draft Specification NFS version 4 Protocol December 1999 4316 NFS4ERR_OLD_STATEID A stateid which designates the locking state 4317 for a lockowner-file at an earlier time was 4318 used. 4320 NFS4ERR_PERM Not owner. The operation was not allowed 4321 because the caller is either not a privileged 4322 user (root) or not the owner of the target of 4323 the operation. 4325 NFS4ERR_READDIR_NOSPC The encoded response to a READDIR request 4326 exceeds the size limit set by the initial 4327 request. 4329 NFS4ERR_RESOURCE For the processing of the COMPOUND procedure, 4330 the server may exhaust available resources and 4331 can not continue processing procedures within 4332 the COMPOUND operation. This error will be 4333 returned from the server in those instances of 4334 resource exhaustion related to the processing 4335 of the COMPOUND procedure. 4337 NFS4ERR_ROFS Read-only file system. A modifying operation 4338 was attempted on a read-only file system. 4340 NFS4ERR_SAME This error is returned by the NVERIFY operation 4341 to signify that the attributes compared were 4342 the same as provided in the client's request. 4344 NFS4ERR_SERVERFAULT An error occurred on the server which does not 4345 map to any of the legal NFS version 4 protocol 4346 error values. The client should translate this 4347 into an appropriate error. UNIX clients may 4348 choose to translate this to EIO. 4350 NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share 4351 reservation has failed because of a share 4352 conflict. 4354 NFS4ERR_STALE Invalid file handle. The file handle given in 4355 the arguments was invalid. The file referred to 4356 by that file handle no longer exists or access 4357 to it has been revoked. 4359 NFS4ERR_STALE_CLIENTID A clientid not recognized by the server was 4360 used in a locking request. 4362 NFS4ERR_STALE_STATEID A stateid generated by an earlier server 4363 instance was used. 4365 Draft Specification NFS version 4 Protocol December 1999 4367 NFS4ERR_SYMLINK The current file handle provided for a LOOKUP 4368 is not a directory but a symbolic link. 4370 NFS4ERR_TOOSMALL Buffer or request is too small. 4372 NFS4ERR_WRONGSEC The security mechanism being used by the client 4373 for the procedure does not match the server's 4374 security policy. The client should change the 4375 security mechanism being used and retry the 4376 operation. 4378 NFS4ERR_XDEV Attempt to do a cross-device hard link. 4380 Draft Specification NFS version 4 Protocol December 1999 4382 13. NFS Version 4 Requests 4384 For the NFS version 4 RPC program, there are two traditional RPC 4385 procedures: NULL and COMPOUND. All other functionality is defined as 4386 a set of operations and these operations are defined in normal 4387 XDR/RPC syntax and semantics. However, these operations are 4388 encapsulated within the COMPOUND procedure. This requires that the 4389 client combine one or more of the NFS version 4 operations into a 4390 single request. 4392 The NFS4_CALLBACK program is used to provide server to client 4393 signaling and is constructed in a similar fashion as the NFS version 4394 4 program. The procedures CB_NULL and CB_COMPOUND are defined in the 4395 same way as NULL and COMPOUND are within the NFS program. The 4396 CB_COMPOUND request also encapsulates the remaining operations of the 4397 NFS4_CALLBACK program. There is no predefined RPC program number for 4398 the NFS4_CALLBACK program. It is up to the client to specify a 4399 program number in the "transient" program range. The program and 4400 port number of the NFS4_CALLBACK program are provided by the client 4401 as part of the SETCLIENTID operation and therefore is fixed for the 4402 life of the client instantiation. 4404 13.1. Compound Procedure 4406 The COMPOUND procedure provides the opportunity for better 4407 performance within high latency networks. The client can avoid 4408 cumulative latency of multiple RPCs by combining multiple dependent 4409 operations into a single COMPOUND procedure. A compound operation 4410 may provide for protocol simplification by allowing the client to 4411 combine basic procedures into a single request that is customized for 4412 the client's environment. 4414 The basics of the COMPOUND procedures construction is: 4416 +-----------+-----------+-----------+-- 4417 | op + args | op + args | op + args | 4418 +-----------+-----------+-----------+-- 4420 and the reply looks like this: 4422 +------------+-----------------------+-----------------------+-- 4423 |last status | status + op + results | status + op + results | 4424 +------------+-----------------------+-----------------------+-- 4426 Draft Specification NFS version 4 Protocol December 1999 4428 13.2. Evaluation of a Compound Request 4430 The server will process the COMPOUND procedure by evaluating each of 4431 the operations within the COMPOUND procedure in order. Each 4432 component operation consists of a 32 bit operation code, followed by 4433 the argument of length determined by the type of operation. The 4434 results of each operation are encoded in sequence into a reply 4435 buffer. The results of each operation are preceded by the opcode and 4436 a status code (normally zero). If an operation results in a non-zero 4437 status code, the status will be encoded and evaluation of the 4438 compound sequence will halt and the reply will be returned. 4440 There are no atomicity requirements for the operations contained 4441 within the COMPOUND procedure. The operations being evaluated as 4442 part of a COMPOUND request may be evaluated simultaneously with other 4443 COMPOUND requests that the server receives. 4445 It is the client's responsibility for recovering from any partially 4446 completed COMPOUND procedure. Therefore, the client should avoid 4447 overly complex COMPOUND procedures in the event of the failure of an 4448 operation with the procedure. 4450 Each operation assumes a "current" and "saved" filehandle that is 4451 available as part of the execution context of the compound request. 4452 Operations may set, change, or return the current filehandle. The 4453 "saved" filehandle is used for temporary storage of a filehandle 4454 value and as operands for the RENAME and LINK operations. 4456 13.3. Operation Values 4458 The operations encoded in the COMPOUND procedure are identified by 4459 operation values. To avoid overlap with the RPC procedure numbers, 4460 operations 0 (zero) and 1 are not defined. Operation 2 it not 4461 defined but reserved for future use with minor versioning. 4463 Draft Specification NFS version 4 Protocol December 1999 4465 14. NFS Version 4 Procedures 4467 14.1. Procedure 0: NULL - No Operation 4469 SYNOPSIS 4471 4473 ARGUMENT 4475 void; 4477 RESULT 4479 void; 4481 DESCRIPTION 4483 Standard NULL procedure. Void argument, void response. This 4484 procedure has no functionality associated with it. Because of this 4485 it is sometimes used to measure the overhead of processing a 4486 service request. Therefore, the server should ensure that no 4487 unnecessary work is done in servicing this procedure. 4489 ERRORS 4491 None. 4493 Draft Specification NFS version 4 Protocol December 1999 4495 14.2. Procedure 1: COMPOUND - Compound Operations 4497 SYNOPSIS 4499 compoundargs -> compoundres 4501 ARGUMENT 4503 union nfs_argop4 switch (nfs_opnum4 argop) { 4504 case : ; 4505 ... 4506 }; 4508 struct COMPOUND4args { 4509 utf8string tag; 4510 uint32_t minorversion; 4511 nfs_argop4 argarray<>; 4512 }; 4514 RESULT 4516 union nfs_resop4 switch (nfs_opnum4 resop){ 4517 case : ; 4518 ... 4519 }; 4521 struct COMPOUND4res { 4522 nfsstat4 status; 4523 utf8string tag; 4524 nfs_resop4 resarray<>; 4525 }; 4527 DESCRIPTION 4529 The COMPOUND procedure is used to combine one or more of the NFS 4530 operations into a single RPC request. The main NFS RPC program has 4531 two main procedures: NULL and COMPOUND. All other operations use 4532 the COMPOUND procedure as a wrapper. 4534 The COMPOUND procedure is used to combine individual operations 4535 into a single RPC request. The server interprets each of the 4536 operations in turn. If an operation is executed by the server and 4537 the status of that operation is NFS4_OK, then the next operation in 4539 Draft Specification NFS version 4 Protocol December 1999 4541 the COMPOUND procedure is executed. The server continues this 4542 process until there are no more operations to be executed or one of 4543 the operations has a status value other than NFS4_OK. 4545 In the processing of the COMPOUND procedure, the server may find 4546 that it does not have the available resources to execute any or all 4547 of the operations within the COMPOUND sequence. In this case, the 4548 error NFS4ERR_RESOURCE will be returned for the particular 4549 operation within the COMPOUND procedure where the resource 4550 exhaustion occurred. This assumes that all previous operations 4551 within the COMPOUND sequence have been evaluated successfully. The 4552 results for all of the evaluated operations must be returned to the 4553 client. 4555 The COMPOUND arguments contain a "minorversion" field. The initial 4556 and default value for this field is 0 (zero). This field will be 4557 used by future minor versions such that the client can communicate 4558 to the server what minor version is being requested. If the server 4559 receives a COMPOUND procedure with a minorversion field value that 4560 it does not support, the server MUST return an error of 4561 NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata array. 4563 Contained within the COMPOUND results is a "status" field. If the 4564 results array length is non-zero, this status must be equivalent to 4565 the status of the last operation that was executed within the 4566 COMPOUND procedure. Therefore, if an operation incurred an error 4567 then the "status" value will be the same error value as is being 4568 returned for the operation that failed. 4570 Note that operations, 0 (zero) and 1 (one) are not defined for the 4571 COMPOUND procedure. If the server receives an operation array with 4572 either of these included, an error of NFS4ERR_NOTSUPP must be 4573 returned. Operation 2 is not defined but reserved for future 4574 definition and use with minor versioning. If the server receives a 4575 operation array that contains operation 2 and the minorversion 4576 field has a value of 0 (zero), an error of NFS4ERR_NOTSUPP is 4577 returned. If an operation array contains an operation 2 and the 4578 minorversion field is non-zero and the server does not support the 4579 minor version, the server returns an error of 4580 NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the 4581 NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other 4582 errors. 4584 IMPLEMENTATION 4586 Note that the definition of the "tag" in both the request and 4588 Draft Specification NFS version 4 Protocol December 1999 4590 response are left to the implementor. It may be used to summarize 4591 the content of the compound request for the benefit of packet 4592 sniffers and engineers debugging implementations. 4594 Since an error of any type may occur after only a portion of the 4595 operations have been evaluated, the client must be prepared to 4596 recover from any failure. If the source of an NFS4ERR_RESOURCE 4597 error was a complex or lengthy set of operations, it is likely that 4598 if the number of operations were reduced the server would be able 4599 to evaluate them successfully. Therefore, the client is 4600 responsible for dealing with this type of complexity in recovery. 4602 ERRORS 4604 All errors defined in the protocol 4606 Draft Specification NFS version 4 Protocol December 1999 4608 14.2.1. Operation 3: ACCESS - Check Access Rights 4610 SYNOPSIS 4612 (cfh), accessreq -> supported, accessrights 4614 ARGUMENT 4616 const ACCESS4_READ = 0x00000001; 4617 const ACCESS4_LOOKUP = 0x00000002; 4618 const ACCESS4_MODIFY = 0x00000004; 4619 const ACCESS4_EXTEND = 0x00000008; 4620 const ACCESS4_DELETE = 0x00000010; 4621 const ACCESS4_EXECUTE = 0x00000020; 4623 struct ACCESS4args { 4624 /* CURRENT_FH: object */ 4625 uint32_t access; 4626 }; 4628 RESULT 4630 struct ACCESS4resok { 4631 uint32_t supported; 4632 uint32_t access; 4633 }; 4635 union ACCESS4res switch (nfsstat4 status) { 4636 case NFS4_OK: 4637 ACCESS4resok resok4; 4638 default: 4639 void; 4640 }; 4642 DESCRIPTION 4644 ACCESS determines the access rights that a user, as identified by 4645 the credentials in the RPC request, has with respect to the file 4646 system object specified by the current filehandle. The client 4647 encodes the set of access rights that are to be checked in the bit 4648 mask "access". The server checks the permissions encoded in the 4649 bit mask. If a status of NFS4_OK is returned, two bit masks are 4650 included in the response. The first, "supported", represents the 4652 Draft Specification NFS version 4 Protocol December 1999 4654 access rights for which the server can verify reliably. The 4655 second, "access", represents the access rights available to the 4656 user for the filehandle provided. On success, the current 4657 filehandle retains its value. 4659 Note that the supported field will contain only as many values as 4660 was originally sent in the arguments. For example, if the client 4661 sends an ACCESS operation with only the ACCESS4_READ value set and 4662 the server supports this value, the server will return only 4663 ACCESS4_READ even if it could have reliably checked other values. 4665 The results of this operation are necessarily advisory in nature. 4666 A return status of NFS4_OK and the appropriate bit set in the bit 4667 mask does not imply that such access will be allowed to the file 4668 system object in the future. This is because access rights can be 4669 revoked by the server at any time. 4671 The following access permissions may be requested: 4673 ACCESS4_READ Read data from file or read a directory. 4675 ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- 4676 directory objects). 4678 ACCESS4_MODIFY Rewrite existing file data or modify existing 4679 directory entries. 4681 ACCESS4_EXTEND Write new data or add directory entries. 4683 ACCESS4_DELETE Delete an existing directory entry (no meaning for 4684 non-directory objects). 4686 ACCESS4_EXECUTE Execute file (no meaning for a directory). 4688 IMPLEMENTATION 4690 In general, it is not sufficient for the client to attempt to 4691 deduce access permissions by inspecting the uid, gid, and mode 4692 fields in the file attributes. This is because the server may 4693 perform uid or gid mapping or enforce additional access control 4694 restrictions. It is also possible that the server may not be in 4695 the same ID space as the client. In these cases (and perhaps 4696 others), the client can not reliably perform an access check with 4697 only current file attributes. 4699 In the NFS version 2 protocol, the only reliable way to determine 4701 Draft Specification NFS version 4 Protocol December 1999 4703 whether an operation was allowed was to try it and see if it 4704 succeeded or failed. Using the ACCESS procedure in the NFS version 4705 4 protocol, the client can ask the server to indicate whether or 4706 not one or more classes of operations are permitted. The ACCESS 4707 operation is provided to allow clients to check before doing a 4708 series of operations. This is useful in operating systems (such as 4709 UNIX) where permission checking is done only when a directory is 4710 opened. The intent is to make the behavior of opening a remote 4711 file more consistent with the behavior of opening a local file. 4713 For the NFS version 4 protocol, the use of the ACCESS procedure 4714 when opening a regular file is deprecated in favor of using OPEN. 4716 The information returned by the server in response to an ACCESS 4717 call is not permanent. It was correct at the exact time that the 4718 server performed the checks, but not necessarily afterwards. The 4719 server can revoke access permission at any time. 4721 The client should use the effective credentials of the user to 4722 build the authentication information in the ACCESS request used to 4723 determine access rights. It is the effective user and group 4724 credentials that are used in subsequent read and write operations. 4726 Many implementations do not directly support the ACCESS_DELETE 4727 permission. Operating systems like UNIX will ignore the 4728 ACCESS_DELETE bit if set on an access request on a non-directory 4729 object. In these systems, delete permission on a file is 4730 determined by the access permissions on the directory in which the 4731 file resides, instead of being determined by the permissions of the 4732 file itself. Therefore, the mask returned enumerating which access 4733 rights can be determined will have the ACCESS_DELETE value set to 4734 0. This indicates to the client that the server was unable to 4735 check that particular access right. The ACCESS_DELETE bit in the 4736 access mask returned will then be ignored by the client. 4738 ERRORS 4740 NFS4ERR_IO 4741 NFS4ERR_ACCES 4742 NFS4ERR_SERVERFAULT 4743 NFS4ERR_STALE 4744 NFS4ERR_BADHANDLE 4745 NFS4ERR_FHEXPIRED 4746 NFS4ERR_WRONGSEC 4747 NFS4ERR_MOVED 4748 NFS4ERR_RESOURCE 4750 Draft Specification NFS version 4 Protocol December 1999 4752 14.2.2. Operation 4: CLOSE - Close File 4754 SYNOPSIS 4756 (cfh), stateid -> stateid 4758 ARGUMENT 4760 struct CLOSE4args { 4761 /* CURRENT_FH: object */ 4762 stateid4 stateid; 4763 }; 4765 RESULT 4767 union CLOSE4res switch (nfsstat4 status) { 4768 case NFS4_OK: 4769 stateid4 stateid; 4770 default: 4771 void; 4772 }; 4774 DESCRIPTION 4776 The CLOSE operation releases share reservations for the file as 4777 specified by the current filehandle. The share reservations and 4778 other state information released at the server as a result of this 4779 CLOSE is only associated with the supplied stateid. State 4780 associated with other OPENs is not affected. 4782 If record locks are held, the client SHOULD release all locks 4783 before issuing a CLOSE. The server MAY free all outstanding locks 4784 on CLOSE but some servers may not support the CLOSE of a file that 4785 still has record locks held. The server MUST return failure if any 4786 locks would exist after the CLOSE. 4788 On success, the current filehandle retains its value. 4790 IMPLEMENTATION 4792 Draft Specification NFS version 4 Protocol December 1999 4794 ERRORS 4796 NFS4ERR_BADHANDLE 4797 NFS4ERR_BAD_STATEID 4798 NFS4ERR_EXPIRED 4799 NFS4ERR_FHEXPIRED 4800 NFS4ERR_GRACE 4801 NFS4ERR_INVAL 4802 NFS4ERR_MOVED 4803 NFS4ERR_OLD_STATEID 4804 NFS4ERR_RESOURCE 4805 NFS4ERR_SERVERFAULT 4806 NFS4ERR_STALE 4807 NFS4ERR_STALE_STATEID 4809 Draft Specification NFS version 4 Protocol December 1999 4811 14.2.3. Operation 5: COMMIT - Commit Cached Data 4813 SYNOPSIS 4815 (cfh), offset, count -> verifier 4817 ARGUMENT 4819 struct COMMIT4args { 4820 /* CURRENT_FH: file */ 4821 offset4 offset; 4822 count4 count; 4823 }; 4825 RESULT 4827 struct COMMIT4resok { 4828 writeverf4 verf; 4829 }; 4831 union COMMIT4res switch (nfsstat4 status) { 4832 case NFS4_OK: 4833 COMMIT4resok resok4; 4834 default: 4835 void; 4836 }; 4838 DESCRIPTION 4840 The COMMIT operation forces or flushes data to stable storage for 4841 the file specified by the current file handle. The flushed data is 4842 that which was previously written with a WRITE operation which had 4843 the stable field set to UNSTABLE4. 4845 The offset specifies the position within the file where the flush 4846 is to begin. An offset value of 0 (zero) means to flush data 4847 starting at the beginning of the file. The count specifies the 4848 number of bytes of data to flush. If count is 0 (zero), a flush 4849 from offset to the end of the file is done. 4851 The server returns a write verifier upon successful completion of 4852 the COMMIT. The write verifier is used by the client to determine 4853 if the server has restarted or rebooted between the initial 4854 WRITE(s) and the COMMIT. The client does this by comparing the 4855 write verifier returned from the initial writes and the verifier 4857 Draft Specification NFS version 4 Protocol December 1999 4859 returned by the COMMIT procedure. The server must vary the value 4860 of the write verifier at each server event or instantiation that 4861 may lead to a loss of uncommitted data. Most commonly this occurs 4862 when the server is rebooted; however, other events at the server 4863 may result in uncommitted data loss as well. 4865 On success, the current filehandle retains its value. 4867 IMPLEMENTATION 4869 The COMMIT procedure is similar in operation and semantics to the 4870 POSIX fsync(2) system call that synchronizes a file's state with 4871 the disk (file data and metadata is flushed to disk or stable 4872 storage). COMMIT performs the same operation for a client, flushing 4873 any unsynchronized data and metadata on the server to the server's 4874 disk or stable storage for the specified file. Like fsync(2), it 4875 may be that there is some modified data or no modified data to 4876 synchronize. The data may have been synchronized by the server's 4877 normal periodic buffer synchronization activity. COMMIT should 4878 return NFS4_OK, unless there has been an unexpected error. 4880 COMMIT differs from fsync(2) in that it is possible for the client 4881 to flush a range of the file (most likely triggered by a buffer- 4882 reclamation scheme on the client before file has been completely 4883 written). 4885 The server implementation of COMMIT is reasonably simple. If the 4886 server receives a full file COMMIT request, that is starting at 4887 offset 0 and count 0, it should do the equivalent of fsync()'ing 4888 the file. Otherwise, it should arrange to have the cached data in 4889 the range specified by offset and count to be flushed to stable 4890 storage. In both cases, any metadata associated with the file must 4891 be flushed to stable storage before returning. It is not an error 4892 for there to be nothing to flush on the server. This means that 4893 the data and metadata that needed to be flushed have already been 4894 flushed or lost during the last server failure. 4896 The client implementation of COMMIT is a little more complex. 4897 There are two reasons for wanting to commit a client buffer to 4898 stable storage. The first is that the client wants to reuse a 4899 buffer. In this case, the offset and count of the buffer are sent 4900 to the server in the COMMIT request. The server then flushes any 4901 cached data based on the offset and count, and flushes any metadata 4902 associated with the file. It then returns the status of the flush 4903 and the write verifier. The other reason for the client to 4904 generate a COMMIT is for a full file flush, such as may be done at 4905 close. In this case, the client would gather all of the buffers 4907 Draft Specification NFS version 4 Protocol December 1999 4909 for this file that contain uncommitted data, do the COMMIT 4910 operation with an offset of 0 and count of 0, and then free all of 4911 those buffers. Any other dirty buffers would be sent to the server 4912 in the normal fashion. 4914 After a buffer is written by the client with the stable parameter 4915 set to UNSTABLE4, the buffer must be considered as modified by the 4916 client until the buffer has either been flushed via a COMMIT 4917 operation or written via a WRITE operation with stable parameter 4918 set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer 4919 from being freed and reused before the data can be flushed to 4920 stable storage on the server. 4922 When a response is returned from either a WRITE or a COMMIT 4923 operation and it contains a write verifier that is different than 4924 previously returned by the server, the client will need to 4925 retransmit all of the buffers containing uncommitted cached data to 4926 the server. How this is to be done is up to the implementor. If 4927 there is only one buffer of interest, then it should probably be 4928 sent back over in a WRITE request with the appropriate stable 4929 parameter. If there is more than one buffer, it might be 4930 worthwhile retransmitting all of the buffers in WRITE requests with 4931 the stable parameter set to UNSTABLE4 and then retransmitting the 4932 COMMIT operation to flush all of the data on the server to stable 4933 storage. The timing of these retransmissions is left to the 4934 implementor. 4936 The above description applies to page-cache-based systems as well 4937 as buffer-cache-based systems. In those systems, the virtual 4938 memory system will need to be modified instead of the buffer cache. 4940 ERRORS 4942 NFS4ERR_ACCES 4943 NFS4ERR_BADHANDLE 4944 NFS4ERR_FHEXPIRED 4945 NFS4ERR_IO 4946 NFS4ERR_LOCKED 4947 NFS4ERR_MOVED 4948 NFS4ERR_NOFILEHANDLE 4949 NFS4ERR_RESOURCE 4950 NFS4ERR_ROFS 4951 NFS4ERR_SERVERFAULT 4952 NFS4ERR_STALE 4953 NFS4ERR_WRONGSEC 4955 Draft Specification NFS version 4 Protocol December 1999 4957 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 4959 SYNOPSIS 4961 (cfh), name, type -> (cfh), change_info 4963 ARGUMENT 4965 union createtype4 switch (nfs_ftype4 type) { 4966 case NF4LNK: 4967 linktext4 linkdata; 4968 case NF4BLK: 4969 case NF4CHR: 4970 specdata4 devdata; 4971 case NF4SOCK: 4972 case NF4FIFO: 4973 case NF4DIR: 4974 case NF4ATTRDIR: 4975 void; 4976 }; 4978 struct CREATE4args { 4979 /* CURRENT_FH: directory for creation */ 4980 component4 objname; 4981 createtype4 objtype; 4982 }; 4984 RESULT 4986 struct CREATE4resok { 4987 change_info4 cinfo; 4988 }; 4990 union CREATE4res switch (nfsstat4 status) { 4991 case NFS4_OK: 4992 CREATE4resok resok4; 4993 default: 4994 void; 4995 }; 4997 DESCRIPTION 4999 The CREATE operation creates a non-regular file object in a 5000 directory with a given name. The OPEN procedure MUST be used to 5001 create a regular file. 5003 Draft Specification NFS version 4 Protocol December 1999 5005 The objname specifies the name for the new object. If the objname 5006 has a length of 0 (zero), the error NFS4ERR_INVAL will be returned. 5007 The objtype determines the type of object to be created: directory, 5008 attribute directory, symlink, etc. 5010 If an object of the same name already exists in the directory, the 5011 server will return the error NFS4ERR_EXIST. 5013 For the directory where the new file object was created, the server 5014 returns change_info4 information in cinfo. With the atomic field 5015 of the change_info4 struct, the server will indicate if the before 5016 and after change attributes were obtained atomically with respect 5017 to the file object creation. 5019 The current filehandle is replaced by that of the new object. 5021 IMPLEMENTATION 5023 If the client desires to set attribute values after the create, a 5024 SETATTR operation can be added to the COMPOUND request so that the 5025 appropriate attributes will be set. 5027 ERRORS 5029 NFS4ERR_ACCES 5030 NFS4ERR_BADHANDLE 5031 NFS4ERR_BADTYPE 5032 NFS4ERR_DQUOT 5033 NFS4ERR_EXIST 5034 NFS4ERR_FHEXPIRED 5035 NFS4ERR_INVAL 5036 NFS4ERR_IO 5037 NFS4ERR_MOVED 5038 NFS4ERR_NAMETOOLONG 5039 NFS4ERR_NOFILEHANDLE 5040 NFS4ERR_NOSPC 5041 NFS4ERR_NOTDIR 5042 NFS4ERR_NOTSUPP 5043 NFS4ERR_RESOURCE 5044 NFS4ERR_ROFS 5045 NFS4ERR_SERVERFAULT 5046 NFS4ERR_STALE 5047 NFS4ERR_WRONGSEC 5048 NFS4ERR_WRONGSEC 5050 Draft Specification NFS version 4 Protocol December 1999 5052 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery 5054 SYNOPSIS 5056 clientid -> 5058 ARGUMENT 5060 struct DELEGPURGE4args { 5061 clientid4 clientid; 5062 }; 5064 RESULT 5066 struct DELEGPURGE4res { 5067 nfsstat4 status; 5068 }; 5070 DESCRIPTION 5072 Purges all of the delegations awaiting recovery for a given client. 5073 This is useful for clients which do not commit delegation 5074 information to stable storage to indicate that conflicting requests 5075 need not be delayed by the server awaiting recovery of delegation 5076 information. 5078 This operation should also be used by clients which do have 5079 delegation information on stable storage after doing all of 5080 delegation recovery that is needed. Using DELEGPURGE will prevent 5081 any delegations which were made by the server but were not sent to 5082 the client and committed to stable storage from holding up other 5083 clients making conflicting requests. 5085 ERRORS 5087 NFS4ERR_RESOURCE 5088 NFS4ERR_STALE_CLIENTID 5090 Draft Specification NFS version 4 Protocol December 1999 5092 14.2.6. Operation 8: DELEGRETURN - Return Delegation 5094 SYNOPSIS 5096 stateid -> 5098 ARGUMENT 5100 struct DELEGRETURN4args { 5101 stateid4 stateid; 5102 }; 5104 RESULT 5106 struct DELEGRETURN4res { 5107 nfsstat4 status; 5108 }; 5110 DESCRIPTION 5112 Returns the delegation represented by the given stateid. 5114 ERRORS 5116 NFS4ERR_BAD_STATEID 5117 NFS4ERR_OLD_STATEID 5118 NFS4ERR_RESOURCE 5119 NFS4ERR_STALE_STATEID 5121 Draft Specification NFS version 4 Protocol December 1999 5123 14.2.7. Operation 9: GETATTR - Get Attributes 5125 SYNOPSIS 5127 (cfh), attrbits -> attrbits, attrvals 5129 ARGUMENT 5131 struct GETATTR4args { 5132 /* CURRENT_FH: directory or file */ 5133 bitmap4 attr_request; 5134 }; 5136 RESULT 5138 struct GETATTR4resok { 5139 fattr4 obj_attributes; 5140 }; 5142 union GETATTR4res switch (nfsstat4 status) { 5143 case NFS4_OK: 5144 GETATTR4resok resok4; 5145 default: 5146 void; 5147 }; 5149 DESCRIPTION 5151 The GETATTR operation will obtain attributes for the file system 5152 object specified by the current filehandle. The client sets a bit 5153 in the bitmap argument for each attribute value that it would like 5154 the server to return. The server returns an attribute bitmap that 5155 indicates the attribute values for which it was able to return, 5156 followed by the attribute values ordered lowest attribute number 5157 first. 5159 The server must return a value for each attribute that the client 5160 requests if the attribute is supported by the server. If the 5161 server does not support an attribute or cannot approximate a useful 5162 value then it must not return the attribute value and must not set 5163 the attribute bit in the result bitmap. The server must return an 5164 error if it supports an attribute but cannot obtain its value. In 5165 that case no attribute values will be returned. 5167 All servers must support the mandatory attributes as specified in 5169 Draft Specification NFS version 4 Protocol December 1999 5171 the section "File Attributes". 5173 On success, the current filehandle retains its value. 5175 IMPLEMENTATION 5177 ERRORS 5179 NFS4ERR_ACCES 5180 NFS4ERR_BADHANDLE 5181 NFS4ERR_FHEXPIRED 5182 NFS4ERR_INVAL 5183 NFS4ERR_IO 5184 NFS4ERR_JUKEBOX 5185 NFS4ERR_MOVED 5186 NFS4ERR_NOFILEHANDLE 5187 NFS4ERR_RESOURCE 5188 NFS4ERR_SERVERFAULT 5189 NFS4ERR_STALE 5190 NFS4ERR_WRONGSEC 5192 Draft Specification NFS version 4 Protocol December 1999 5194 14.2.8. Operation 10: GETFH - Get Current Filehandle 5196 SYNOPSIS 5198 (cfh) -> filehandle 5200 ARGUMENT 5202 /* CURRENT_FH: */ 5203 void; 5205 RESULT 5207 struct GETFH4resok { 5208 nfs_fh4 object; 5209 }; 5211 union GETFH4res switch (nfsstat4 status) { 5212 case NFS4_OK: 5213 GETFH4resok resok4; 5214 default: 5215 void; 5216 }; 5218 DESCRIPTION 5220 This operation returns the current filehandle value. 5222 On success, the current filehandle retains its value. 5224 IMPLEMENTATION 5226 Operations that change the current filehandle like LOOKUP or CREATE 5227 do not automatically return the new filehandle as a result. For 5228 instance, if a client needs to lookup a directory entry and obtain 5229 its filehandle then the following request is needed. 5231 PUTFH (directory filehandle) 5232 LOOKUP (entry name) 5233 GETFH 5235 ERRORS 5237 Draft Specification NFS version 4 Protocol December 1999 5239 NFS4ERR_BADHANDLE 5240 NFS4ERR_FHEXPIRED 5241 NFS4ERR_MOVED 5242 NFS4ERR_NOFILEHANDLE 5243 NFS4ERR_RESOURCE 5244 NFS4ERR_SERVERFAULT 5245 NFS4ERR_STALE 5246 NFS4ERR_WRONGSEC 5248 Draft Specification NFS version 4 Protocol December 1999 5250 14.2.9. Operation 11: LINK - Create Link to a File 5252 SYNOPSIS 5254 (sfh), (cfh), newname -> (cfh), change_info 5256 ARGUMENT 5258 struct LINK4args { 5259 /* SAVED_FH: source object */ 5260 /* CURRENT_FH: target directory */ 5261 component4 newname; 5262 }; 5264 RESULT 5266 struct LINK4resok { 5267 change_info4 cinfo; 5268 }; 5270 union LINK4res switch (nfsstat4 status) { 5271 case NFS4_OK: 5272 LINK4resok resok4; 5273 default: 5274 void; 5275 }; 5277 DESCRIPTION 5279 The LINK operation creates an additional newname for the file 5280 represented by the saved filehandle in the directory represented by 5281 the current filehandle. The existing file and the target directory 5282 must reside within the same file system on the server. On success 5283 the current filehandle represents the newly created file. 5285 For the target directory, the server returns change_info4 5286 information in cinfo. With the atomic field of the change_info4 5287 struct, the server will indicate if the before and after change 5288 attributes were obtained atomically with respect to the link 5289 creation. 5291 If the newname has a length of 0 (zero), the error NFS4ERR_INVAL 5292 will be returned. 5294 Draft Specification NFS version 4 Protocol December 1999 5296 IMPLEMENTATION 5298 Changes to any property of the "hard" linked files are reflected in 5299 all of the linked files. When a link is made to a file, the 5300 attributes for the file should have a value for numlinks that is 5301 one greater than the value before the LINK operation. 5303 The comments under RENAME regarding object and target residing on 5304 the same file system apply here as well. The comments regarding the 5305 target name applies as well. 5307 ERRORS 5309 NFS4ERR_ACCES 5310 NFS4ERR_BADHANDLE 5311 NFS4ERR_DQUOT 5312 NFS4ERR_EXIST 5313 NFS4ERR_FHEXPIRED 5314 NFS4ERR_INVAL 5315 NFS4ERR_IO 5316 NFS4ERR_MLINK 5317 NFS4ERR_MOVED 5318 NFS4ERR_NAMETOOLONG 5319 NFS4ERR_NOSPC 5320 NFS4ERR_NOTDIR 5321 NFS4ERR_NOTSUPP 5322 NFS4ERR_RESOURCE 5323 NFS4ERR_ROFS 5324 NFS4ERR_SERVERFAULT 5325 NFS4ERR_STALE 5326 NFS4ERR_WRONGSEC 5327 NFS4ERR_XDEV 5329 Draft Specification NFS version 4 Protocol December 1999 5331 14.2.10. Operation 12: LOCK - Create Lock 5333 SYNOPSIS 5335 (cfh) type, seqid, reclaim, owner, offset, length -> stateid, 5336 access 5338 ARGUMENT 5340 enum nfs4_lock_type { 5341 READ_LT = 1, 5342 WRITE_LT = 2, 5343 READW_LT = 3, /* blocking read */ 5344 WRITEW_LT = 4 /* blocking write */ 5345 }; 5347 struct LOCK4args { 5348 /* CURRENT_FH: file */ 5349 nfs_lock_type4 locktype; 5350 seqid4 seqid; 5351 bool reclaim; 5352 stateid4 stateid; 5353 offset4 offset; 5354 length4 length; 5355 }; 5357 RESULT 5359 union LOCK4res switch (nfsstat4 status) { 5360 case NFS4_OK: 5361 stateid4 stateid; 5362 default: 5363 void; 5364 }; 5366 DESCRIPTION 5368 The LOCK operation requests a record lock for the byte range 5369 specified by the offset and length parameters. The lock type is 5370 also specified to be one of the nfs4_lock_types. If this is a 5371 reclaim request, the reclaim parameter will be TRUE; 5373 To lock the whole or entire file, the offset value should be 0 5374 (zero) and the length should have a value of all 1's (maximum value 5376 Draft Specification NFS version 4 Protocol December 1999 5378 for length4 data type). 5380 On success, the current filehandle retains its value. 5382 IMPLEMENTATION 5384 The File Locking section contains a full description of this and 5385 the other file locking operations. 5387 ERRORS 5389 NFS4ERR_ACCES 5390 NFS4ERR_BADHANDLE 5391 NFS4ERR_BAD_SEQID 5392 NFS4ERR_BAD_STATEID 5393 NFS4ERR_DENIED 5394 NFS4ERR_EXPIRED 5395 NFS4ERR_FHEXPIRED 5396 NFS4ERR_GRACE 5397 NFS4ERR_INVAL 5398 NFS4ERR_ISDIR 5399 NFS4ERR_MOVED 5400 NFS4ERR_NOFILEHANDLE 5401 NFS4ERR_OLD_STATEID 5402 NFS4ERR_RESOURCE 5403 NFS4ERR_SERVERFAULT 5404 NFS4ERR_STALE 5405 NFS4ERR_STALE_CLIENTID 5406 NFS4ERR_STALE_STATEID 5407 NFS4ERR_WRONGSEC 5409 Draft Specification NFS version 4 Protocol December 1999 5411 14.2.11. Operation 13: LOCKT - Test For Lock 5413 SYNOPSIS 5415 (cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED -> 5416 owner} 5418 ARGUMENT 5420 struct LOCKT4args { 5421 /* CURRENT_FH: file */ 5422 nfs_lock_type4 locktype; 5423 nfs_lockowner4 owner; 5424 offset4 offset; 5425 length4 length; 5426 }; 5428 RESULT 5430 union LOCKT4res switch (nfsstat4 status) { 5431 case NFS4ERR_DENIED: 5432 nfs_lockowner owner; 5433 case NFS4_OK: 5434 void; 5435 default: 5436 void; 5437 }; 5439 DESCRIPTION 5441 The LOCKT operation tests the lock as specified in the arguments. 5442 The owner of the lock is returned in the event it is currently 5443 being held; if no lock is held, nothing other than NFS4_OK is 5444 returned. 5446 On success, the current filehandle retains its value. 5448 IMPLEMENTATION 5450 The File Locking section contains a full description of this and 5451 the other file locking procedures. 5453 Draft Specification NFS version 4 Protocol December 1999 5455 ERRORS 5457 NFS4ERR_ACCES 5458 NFS4ERR_BADHANDLE 5459 NFS4ERR_DENIED 5460 NFS4ERR_FHEXPIRED 5461 NFS4ERR_GRACE 5462 NFS4ERR_INVAL 5463 NFS4ERR_ISDIR 5464 NFS4ERR_MOVED 5465 NFS4ERR_NOFILEHANDLE 5466 NFS4ERR_RESOURCE 5467 NFS4ERR_SERVERFAULT 5468 NFS4ERR_STALE 5469 NFS4ERR_STALE_CLIENTID 5470 NFS4ERR_WRONGSEC 5472 Draft Specification NFS version 4 Protocol December 1999 5474 14.2.12. Operation 14: LOCKU - Unlock File 5476 SYNOPSIS 5478 (cfh) type, seqid, stateid, offset, length -> stateid 5480 ARGUMENT 5482 struct LOCKU4args { 5483 /* CURRENT_FH: file */ 5484 nfs_lock_type4 type; 5485 seqid4 seqid; 5486 stateid4 stateid; 5487 offset4 offset; 5488 length4 length; 5489 }; 5491 RESULT 5493 union LOCKU4res switch (nfsstat4 status) { 5494 case NFS4_OK: 5495 stateid4 stateid; 5496 default: 5497 void; 5498 }; 5500 DESCRIPTION 5502 The LOCKU operation unlocks the record lock specified by the 5503 parameters. 5505 On success, the current filehandle retains its value. 5507 IMPLEMENTATION 5509 The File Locking section contains a full description of this and 5510 the other file locking procedures. 5512 ERRORS 5514 NFS4ERR_ACCES 5515 NFS4ERR_BADHANDLE 5516 NFS4ERR_BAD_SEQID 5518 Draft Specification NFS version 4 Protocol December 1999 5520 NFS4ERR_BAD_STATEID 5521 NFS4ERR_EXPIRED 5522 NFS4ERR_FHEXPIRED 5523 NFS4ERR_GRACE 5524 NFS4ERR_INVAL 5525 NFS4ERR_MOVED 5526 NFS4ERR_NOFILEHANDLE 5527 NFS4ERR_OLD_STATEID 5528 NFS4ERR_RESOURCE 5529 NFS4ERR_SERVERFAULT 5530 NFS4ERR_STALE 5531 NFS4ERR_STALE_CLIENTID 5533 Draft Specification NFS version 4 Protocol December 1999 5535 14.2.13. Operation 15: LOOKUP - Lookup Filename 5537 SYNOPSIS 5539 (cfh), filenames -> (cfh) 5541 ARGUMENT 5543 struct LOOKUP4args { 5544 /* CURRENT_FH: directory */ 5545 pathname4 path; 5546 }; 5548 RESULT 5550 struct LOOKUP4res { 5551 /* CURRENT_FH: object */ 5552 nfsstat4 status; 5553 }; 5555 DESCRIPTION 5557 This operation LOOKUPs or finds a file system object starting from 5558 the directory specified by the current filehandle. LOOKUP 5559 evaluates the pathname contained in the array of names and obtains 5560 a new current filehandle from the final name. All but the final 5561 name in the list must be the names of directories. 5563 If the pathname cannot be evaluated either because a component does 5564 not exist or because the client does not have permission to 5565 evaluate a component of the path, then an error will be returned 5566 and the current filehandle will be unchanged. 5568 If the path is a zero length array or if any component in the path 5569 is of zero length, the error NFS4ERR_INVAL will be returned. 5571 IMPLEMENTATION 5573 If the client prefers a partial evaluation of the path then a 5574 sequence of LOOKUP operations can be substituted e.g. 5576 Draft Specification NFS version 4 Protocol December 1999 5578 PUTFH (directory filehandle) 5579 LOOKUP "pub" "foo" "bar" 5580 GETFH 5582 or 5584 PUTFH (directory filehandle) 5585 LOOKUP "pub" 5586 GETFH 5587 LOOKUP "foo" 5588 GETFH 5589 LOOKUP "bar" 5590 GETFH 5592 NFS version 4 servers depart from the semantics of previous NFS 5593 versions in allowing LOOKUP requests to cross mountpoints on the 5594 server. The client can detect a mountpoint crossing by comparing 5595 the fsid attribute of the directory with the fsid attribute of the 5596 directory looked up. If the fsids are different then the new 5597 directory is a server mountpoint. Unix clients that detect a 5598 mountpoint crossing will need to mount the server's filesystem. 5600 Servers that limit NFS access to "shares" or "exported" filesystems 5601 should provide a pseudo-filesystem into which the exported 5602 filesystems can be integrated, so that clients can browse the 5603 server's namespace. The clients view of a pseudo filesystem will 5604 be limited to paths that lead to exported filesystems. 5606 Note: previous versions of the protocol assigned special semantics 5607 to the names "." and "..". NFS version 4 assigns no special 5608 semantics to these names. The LOOKUPP operator must be used to 5609 lookup a parent directory. 5611 Note that this procedure does not follow symbolic links. The 5612 client is responsible for all parsing of filenames including 5613 filenames that are modified by symbolic links encountered during 5614 the lookup process. 5616 If the current file handle supplied is not a directory but a 5617 symbolic link, the error NFS4ERR_SYMLINK is returned as the error. 5618 For all other non-directory file types, the error NFS4ERR_NOTDIR is 5619 returned. 5621 ERRORS 5623 NFS4ERR_ACCES 5625 Draft Specification NFS version 4 Protocol December 1999 5627 NFS4ERR_BADHANDLE 5628 NFS4ERR_FHEXPIRED 5629 NFS4ERR_INVAL 5630 NFS4ERR_IO 5631 NFS4ERR_MOVED 5632 NFS4ERR_NAMETOOLONG 5633 NFS4ERR_NOENT 5634 NFS4ERR_NOFILEHANDLE 5635 NFS4ERR_NOTDIR 5636 NFS4ERR_RESOURCE 5637 NFS4ERR_SERVERFAULT 5638 NFS4ERR_STALE 5639 NFS4ERR_SYMLINK 5640 NFS4ERR_WRONGSEC 5642 Draft Specification NFS version 4 Protocol December 1999 5644 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory 5646 SYNOPSIS 5648 (cfh) -> (cfh) 5650 ARGUMENT 5652 /* CURRENT_FH: object */ 5653 void; 5655 RESULT 5657 struct LOOKUPP4res { 5658 /* CURRENT_FH: directory */ 5659 nfsstat4 status; 5660 }; 5662 DESCRIPTION 5664 The current filehandle is assumed to refer to a directory. LOOKUPP 5665 assigns the filehandle for its parent directory to be the current 5666 filehandle. If there is no parent directory an NFS4ERR_ENOENT 5667 error must be returned. Therefore, NFS4ERR_ENOENT will be returned 5668 by the server when the current filehandle is at the root or top of 5669 the server's file tree. 5671 IMPLEMENTATION 5673 As for LOOKUP, LOOKUPP will also cross mountpoints. 5675 ERRORS 5677 NFS4ERR_ACCES 5678 NFS4ERR_BADHANDLE 5679 NFS4ERR_FHEXPIRED 5680 NFS4ERR_INVAL 5681 NFS4ERR_IO 5682 NFS4ERR_MOVED 5683 NFS4ERR_NOENT 5684 NFS4ERR_NOFILEHANDLE 5685 NFS4ERR_RESOURCE 5686 NFS4ERR_SERVERFAULT 5687 NFS4ERR_STALE 5689 Draft Specification NFS version 4 Protocol December 1999 5691 NFS4ERR_WRONGSEC 5693 Draft Specification NFS version 4 Protocol December 1999 5695 14.2.15. Operation 17: NVERIFY - Verify Difference in Attributes 5697 SYNOPSIS 5699 (cfh), attrbits, attrvals -> - 5701 ARGUMENT 5703 struct NVERIFY4args { 5704 /* CURRENT_FH: object */ 5705 bitmap4 attr_request; 5706 fattr4 obj_attributes; 5707 }; 5709 RESULT 5711 struct NVERIFY4res { 5712 nfsstat4 status; 5713 }; 5715 DESCRIPTION 5717 This operation is used to prefix a sequence of operations to be 5718 performed if one or more attributes have changed on some filesystem 5719 object. If all the attributes match then the error NFS4ERR_SAME 5720 must be returned. 5722 IMPLEMENTATION 5724 This operation is useful as a cache validation operator. If the 5725 object to which the attributes belong has changed then the 5726 following operations may obtain new data associated with that 5727 object. For instance, to check if a file has been changed and 5728 obtain new data if it has: 5730 PUTFH (public) 5731 LOOKUP "pub" "foo" "bar" 5732 NVERIFY attrbits attrs 5733 READ 0 32767 5735 ERRORS 5737 Draft Specification NFS version 4 Protocol December 1999 5739 NFS4ERR_ACCES 5740 NFS4ERR_BADHANDLE 5741 NFS4ERR_FHEXPIRED 5742 NFS4ERR_INVAL 5743 NFS4ERR_IO 5744 NFS4ERR_MOVED 5745 NFS4ERR_NOFILEHANDLE 5746 NFS4ERR_RESOURCE 5747 NFS4ERR_SAME 5748 NFS4ERR_SERVERFAULT 5749 NFS4ERR_STALE 5750 NFS4ERR_WRONGSEC 5752 Draft Specification NFS version 4 Protocol December 1999 5754 14.2.16. Operation 18: OPEN - Open a Regular File 5756 SYNOPSIS 5758 (cfh), claim, openhow, owner, seqid, access, deny -> (cfh), 5759 stateid, rflags, open_confirm, delegation 5761 ARGUMENT 5763 struct OPEN4args { 5764 open_claim4 claim; 5765 openflag4 openhow; 5766 nfs_lockowner4 owner; 5767 seqid4 seqid; 5768 uint32_t share_access; 5769 uint32_t share_deny; 5770 }; 5772 enum createmode4 { 5773 UNCHECKED4 = 0, 5774 GUARDED4 = 1, 5775 EXCLUSIVE4 = 2 5776 }; 5778 union createhow4 switch (createmode4 mode) { 5779 case UNCHECKED4: 5780 case GUARDED4: 5781 fattr4 createattrs; 5782 case EXCLUSIVE4: 5783 createverf4 verf; 5784 }; 5786 enum opentype4 { 5787 OPEN4_NOCREATE = 0, 5788 OPEN4_CREATE = 1 5789 }; 5791 union openflag4 switch (opentype4 opentype) { 5792 case OPEN4_CREATE: 5793 createhow4 how; 5794 default: 5795 void; 5796 }; 5798 /* Next definitions used for OPEN delegation */ 5799 enum limit_by4 { 5800 NFS_LIMIT_SIZE = 1, 5802 Draft Specification NFS version 4 Protocol December 1999 5804 NFS_LIMIT_BLOCKS = 2 5805 /* others as needed */ 5806 }; 5808 struct nfs_modified_limit4 { 5809 uint32_t num_blocks; 5810 uint32_t bytes_per_block; 5811 }; 5813 union nfs_space_limit4 switch (limit_by4 limitby) { 5814 /* limit specified as file size */ 5815 case NFS_LIMIT_SIZE: 5816 uint64_t filesize; 5817 /* limit specified by number of blocks */ 5818 case NFS_LIMIT_BLOCKS: 5819 nfs_modified_limit4 mod_blocks; 5820 } ; 5822 /* 5823 * Share Access and Deny constants for open argument 5824 */ 5825 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 5826 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 5827 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 5829 const OPEN4_SHARE_DENY_NONE = 0x00000000; 5830 const OPEN4_SHARE_DENY_READ = 0x00000001; 5831 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 5832 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 5834 enum open_delegation_type4 { 5835 OPEN_DELEGATE_NONE = 0, 5836 OPEN_DELEGATE_READ = 1, 5837 OPEN_DELEGATE_WRITE = 2 5838 }; 5840 enum open_claim_type4 { 5841 CLAIM_NULL = 0, 5842 CLAIM_PREVIOUS = 1, 5843 CLAIM_DELEGATE_CUR = 2, 5844 CLAIM_DELEGATE_PREV = 3 5845 }; 5847 struct open_claim_delegate_cur4 { 5848 pathname4 file; 5849 stateid4 delegate_stateid; 5850 }; 5852 Draft Specification NFS version 4 Protocol December 1999 5854 union open_claim4 switch (open_claim_type4 claim) { 5855 /* 5856 * No special rights to file. Ordinary OPEN of the specified file. 5857 */ 5858 case CLAIM_NULL: 5859 /* CURRENT_FH: directory */ 5860 pathname4 file; 5862 /* 5863 * Right to the file established by an open previous to server 5864 * reboot. File identified by filehandle obtained at that time 5865 * rather than by name. 5866 */ 5867 case CLAIM_PREVIOUS: 5868 /* CURRENT_FH: file being reclaimed */ 5869 uint32_t delegate_type; 5871 /* 5872 * Right to file based on a delegation granted by the server. 5873 * File is specified by name. 5874 */ 5875 case CLAIM_DELEGATE_CUR: 5876 /* CURRENT_FH: directory */ 5877 open_claim_delegate_cur4 delegate_cur_info; 5879 /* Right to file based on a delegation granted to a previous boot 5880 * instance of the client. File is specified by name. 5881 */ 5882 case CLAIM_DELEGATE_PREV: 5883 /* CURRENT_FH: directory */ 5884 pathname4 file_delegate_prev; 5885 }; 5887 RESULT 5889 const OPEN4_RESULT_MLOCK = 0x00000001; 5891 struct open_read_delegation4 { 5892 stateid4 stateid; /* Stateid for delegation*/ 5893 bool recall; /* Pre-recalled flag for 5894 delegations obtained 5895 by reclaim 5896 (CLAIM_PREVIOUS) */ 5897 nfsace4 permissions; /* Defines users who don't 5898 need an ACCESS call to 5899 open for read */ 5901 Draft Specification NFS version 4 Protocol December 1999 5903 }; 5905 struct open_write_delegation4 { 5906 stateid4 stateid; /* Stateid for delegation 5907 be flushed to the server 5908 on close. */ 5909 bool recall; /* Pre-recalled flag for 5910 delegations obtained 5911 by reclaim 5912 (CLAIM_PREVIOUS) */ 5913 nfs_space_limit4 space_limit; /* Defines condition that 5914 the client must check to 5915 determine whether the 5916 file needs to be flushed 5917 to the server on close. 5918 */ 5919 nfsace4 permissions; /* Defines users who don't 5920 need an ACCESS call as 5921 part of a delegated 5922 open. */ 5923 }; 5925 union open_delegation4 5926 switch (open_delegation_type4 delegation_type) { 5927 case OPEN_DELEGATE_NONE: 5928 void; 5929 case OPEN_DELEGATE_READ: 5930 open_read_delegation4 read; 5931 case OPEN_DELEGATE_WRITE: 5932 open_write_delegation4 write; 5933 }; 5935 struct OPEN4resok { 5936 stateid4 stateid; /* Stateid for open */ 5937 uint32_t rflags; /* Result flags */ 5938 cookieverf4 open_confirm; /* OPEN_CONFIRM verifier */ 5939 open_delegation4 delegation; /* Info on any open 5940 delegation */ 5941 }; 5943 union OPEN4res switch (nfsstat4 status) { 5944 case NFS4_OK: 5945 /* CURRENT_FH: opened file */ 5946 OPEN4resok result; 5947 default: 5948 void; 5949 }; 5951 Draft Specification NFS version 4 Protocol December 1999 5953 DESCRIPTION 5955 The OPEN operation creates and/or opens a regular file in a 5956 directory with the provided name. If the file does not exist at 5957 the server and creation is desired, specification of the method of 5958 creation is provided by the openhow parameter. The client has the 5959 choice of three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE. 5961 UNCHECKED means that the file should be created without checking 5962 for the existence of a duplicate object in the same directory. For 5963 this type of create, createattrs specifies the initial set of 5964 attributes for the file (NOTE: need to define exactly which 5965 attributes should be set and if the file exists, should the 5966 attributes be modified if the file exists). If GUARDED is 5967 specified, the server checks for the presence of a duplicate object 5968 by name before performing the create. If a duplicate exists, an 5969 error of NFS4ERR_EXIST is returned as the status. If the object 5970 does not exist, the request is performed as described for 5971 UNCHECKED. 5973 EXCLUSIVE specifies that the server is to follow exclusive creation 5974 semantics, using the verifier to ensure exclusive creation of the 5975 target. The server should check for the presence of a duplicate 5976 object by name. If the object does not exist, the server creates 5977 the object and stores the verifier with the object. If the object 5978 does exist and the stored verifier matches the client provided 5979 verifier, the server uses the existing object as the newly created 5980 object. If the stored verifier does not match, then an error of 5981 NFS4ERR_EXIST is returned. No attributes may be provided in this 5982 case, since the server may use an attribute of the target object to 5983 store the verifier. (NOTE: does a specific attribute need to be 5984 specified for storage of verifier ) 5986 Upon successful creation, the current filehandle is replaced by 5987 that of the new object. 5989 The OPEN procedure provides for DOS SHARE capability with the use 5990 of the access and deny fields of the OPEN arguments. The client 5991 specifies at OPEN the required access and deny modes. For clients 5992 that do not directly support SHAREs (i.e. Unix), the expected deny 5993 value is DENY_NONE. In the case that there is a existing SHARE 5994 reservation that conflicts with the OPEN request, the server 5995 returns the error NFS4ERR_DENIED. For a complete SHARE request, 5996 the client must provide values for the owner and seqid fields for 5997 the OPEN argument. For additional discussion of SHARE semantics 5998 see the section on 'Share Reservations'. 6000 In the case that the client is recovering state from a server 6002 Draft Specification NFS version 4 Protocol December 1999 6004 failure, the reclaim field of the OPEN argument is used to signify 6005 that the request is meant to reclaim state previously held. 6007 The "claim" field of the OPEN argument is used to specify the file 6008 to be opened and the state information which the client claims to 6009 possess. There are four basic claim types which cover the various 6010 situations for an OPEN. They are as follows: 6012 CLAIM_NULL For the client, this is a new OPEN 6013 request and there is no previous state 6014 associate with the file for the client. 6016 CLAIM_PREVIOUS The client is claiming basic OPEN state 6017 for a file that was held previous to a 6018 server reboot. Generally used when a 6019 server is returning persistent file 6020 handles; the client may not have the 6021 file name to reclaim the OPEN. 6023 CLAIM_DELEGATE_CUR The client is claiming a delegation for 6024 OPEN as granted by the server. 6025 Generally this is done as part of 6026 recalling a delegation. 6028 CLAIM_DELEGATE_PREV The client is claiming a delegation 6029 granted to a previous client instance; 6030 used after the client reboots. 6032 For OPEN requests whose claim type is other than CLAIM_PREVIOUS 6033 (i.e. requests other than those devoted to reclaiming opens after a 6034 server reboot) that reach the server during its grace or lease 6035 expiration period, the server returns an error of NFS4ERR_GRACE. 6037 For any OPEN request, the server may return an open delegation, 6038 which allows further opens and closes to be handled locally on the 6039 client as described in the section Open Delegation. Note that 6040 delegation is up to the server to decide. The client should never 6041 assume that delegation will or will not be granted in a particular 6042 instance. It should always be prepared for either case. A partial 6043 exception is the reclaim (CLAIM_PREVIOUS) case, in which a 6044 delegation type is claimed. In this case, delegation will always 6045 be granted, although the server may specify an immediate recall in 6046 the delegation structure. 6048 IMPLEMENTATION 6050 Draft Specification NFS version 4 Protocol December 1999 6052 The OPEN procedure contains support for EXCLUSIVE create. The 6053 mechanism is similar to the support in NFS version 3 [RFC1813]. As 6054 in NFS version 3, this mechanism provides reliable exclusive 6055 creation. Exclusive create is invoked when the how parameter is 6056 EXCLUSIVE. In this case, the client provides a verifier that can 6057 reasonably be expected to be unique. A combination of a client 6058 identifier, perhaps the client network address, and a unique number 6059 generated by the client, perhaps the RPC transaction identifier, 6060 may be appropriate. 6062 If the object does not exist, the server creates the object and 6063 stores the verifier in stable storage. For file systems that do not 6064 provide a mechanism for the storage of arbitrary file attributes, 6065 the server may use one or more elements of the object meta-data to 6066 store the verifier. The verifier must be stored in stable storage 6067 to prevent erroneous failure on retransmission of the request. It 6068 is assumed that an exclusive create is being performed because 6069 exclusive semantics are critical to the application. Because of the 6070 expected usage, exclusive CREATE does not rely solely on the 6071 normally volatile duplicate request cache for storage of the 6072 verifier. The duplicate request cache in volatile storage does not 6073 survive a crash and may actually flush on a long network partition, 6074 opening failure windows. In the UNIX local file system 6075 environment, the expected storage location for the verifier on 6076 creation is the meta-data (time stamps) of the object. For this 6077 reason, an exclusive object create may not include initial 6078 attributes because the server would have nowhere to store the 6079 verifier. 6081 If the server can not support these exclusive create semantics, 6082 possibly because of the requirement to commit the verifier to 6083 stable storage, it should fail the OPEN request with the error, 6084 NFS4ERR_NOTSUPP. 6086 During an exclusive CREATE request, if the object already exists, 6087 the server reconstructs the object's verifier and compares it with 6088 the verifier in the request. If they match, the server treats the 6089 request as a success. The request is presumed to be a duplicate of 6090 an earlier, successful request for which the reply was lost and 6091 that the server duplicate request cache mechanism did not detect. 6092 If the verifiers do not match, the request is rejected with the 6093 status, NFS4ERR_EXIST. 6095 Once the client has performed a successful exclusive create, it 6096 must issue a SETATTR to set the correct object attributes. Until 6097 it does so, it should not rely upon any of the object attributes, 6098 since the server implementation may need to overload object meta- 6099 data to store the verifier. The subsequent SETATTR must not occur 6101 Draft Specification NFS version 4 Protocol December 1999 6103 in the same COMPOUND request as the OPEN. This separation will 6104 guarantee that the exclusive create mechanism will continue to 6105 function properly in the face of retransmission of the request. 6107 Use of the GUARDED attribute does not provide exactly-once 6108 semantics. In particular, if a reply is lost and the server does 6109 not detect the retransmission of the request, the procedure can 6110 fail with NFS4ERR_EXIST, even though the create was performed 6111 successfully. 6113 For SHARE reservations, the client must specify a value for access 6114 that is one of READ, WRITE, or BOTH. For deny, the client must 6115 specify one of NONE, READ, WRITE, or BOTH. If the client fails to 6116 do this, the server must return NFS4ERR_INVAL. 6118 ERRORS 6120 NFS4ERR_ACCES 6121 NFS4ERR_BAD_SEQID 6122 NFS4ERR_DQUOT 6123 NFS4ERR_EXIST 6124 NFS4ERR_GRACE 6125 NFS4ERR_IO 6126 NFS4ERR_MOVED 6127 NFS4ERR_NAMETOOLONG 6128 NFS4ERR_NOSPC 6129 NFS4ERR_NOTDIR 6130 NFS4ERR_NOTSUPP 6131 NFS4ERR_RESOURCE 6132 NFS4ERR_ROFS 6133 NFS4ERR_SERVERFAULT 6134 NFS4ERR_SHARE_DENIED 6135 NFS4ERR_STALE_CLIENTID 6137 Draft Specification NFS version 4 Protocol December 1999 6139 14.2.17. Operation 19: OPENATTR - Open Named Attribute Directory 6141 SYNOPSIS 6143 (cfh) -> (cfh) 6145 ARGUMENT 6147 /* CURRENT_FH: file or directory */ 6148 void; 6150 RESULT 6152 struct OPENATTR4res { 6153 /* CURRENT_FH: name attr directory*/ 6154 nfsstat4 status; 6155 }; 6157 DESCRIPTION 6159 The OPENATTR operation is used to obtain the filehandle of the 6160 named attribute directory associated with the current filehandle. 6161 The result of the OPENATTR will be a filehandle of type NF4ATTRDIR. 6162 From this filehandle, READDIR and LOOKUP procedures can be used to 6163 obtain filehandles for the various named attributes associated with 6164 the original file system object. Filehandles returned within the 6165 named attribute directory will have a type of NF4NAMEDATTR. 6167 IMPLEMENTATION 6169 If the server does not support named attributes for the current 6170 filehandle, an error of NFS4ERR_NOTSUPP will be returned to the 6171 client. 6173 ERRORS 6175 NFS4ERR_ACCES 6176 NFS4ERR_BADHANDLE 6177 NFS4ERR_FHEXPIRED 6178 NFS4ERR_INVAL 6179 NFS4ERR_IO 6180 NFS4ERR_JUKEBOX 6181 NFS4ERR_MOVED 6183 Draft Specification NFS version 4 Protocol December 1999 6185 NFS4ERR_NOENT 6186 NFS4ERR_NOFILEHANDLE 6187 NFS4ERR_NOTSUPP 6188 NFS4ERR_RESOURCE 6189 NFS4ERR_SERVERFAULT 6190 NFS4ERR_STALE 6191 NFS4ERR_WRONGSEC 6193 Draft Specification NFS version 4 Protocol December 1999 6195 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open 6197 SYNOPSIS 6199 (cfh), seqid, open_confirm-> stateid 6201 ARGUMENT 6203 struct OPEN_CONFIRM4args { 6204 /* CURRENT_FH: opened file */ 6205 seqid4 seqid; 6206 cookieverf4 open_confirm; /* OPEN_CONFIRM verifier */ 6207 }; 6209 RESULT 6211 struct OPEN_CONFIRM4resok { 6212 stateid4 stateid; 6213 }; 6215 union OPEN_CONFIRM4res switch (nfsstat4 status) { 6216 case NFS4_OK: 6217 OPEN_CONFIRM4resok resok4; 6218 default: 6219 void; 6220 }; 6222 DESCRIPTION 6224 This operation is used to confirm the sequence id usage for the 6225 first time that a nfs_lockowner is used by a client. The OPEN 6226 operation returns a opaque confirmation cookie that is then passed 6227 to this operation along with the next sequence id for the 6228 nfs_lockowner. The sequence id passed to the OPEN_CONFIRM must be 6229 1 (one) greater than the seqid passed to the OPEN operation from 6230 which the open_confirm value was obtained. If the receives an 6231 unexpected sequence id with respect to the original open, then the 6232 server assumes that the client will not confirm the original OPEN 6233 and all state associated with the original OPEN is released by the 6234 server. 6236 On success, the current filehandle retains its value. 6238 IMPLEMENTATION 6240 Draft Specification NFS version 4 Protocol December 1999 6242 When the client first initiates contact with a server for a 6243 particular nfs_lockowner, the sequence id value needs to be 6244 confirmed with the server. The two step process of OPENing a file 6245 and then OPEN_CONFIRMing the sequence id for the nfs_lockowner is 6246 meant to deal with an OPEN operation that is retransmitted within 6247 the network. The server must hold unconfirmed OPEN state until one 6248 of three events occur. The client sends an OPEN_CONFIRM request 6249 with the appropriate sequence id and confirmation cookie within the 6250 lease period. Second, the client sends a request with a sequence 6251 id that incorrect for the nfs_lockowner (out of sequence). Third, 6252 the client send no request for the nfs_lockowner within the lease 6253 period. 6255 ERRORS 6257 NFS4ERR_BADHANDLE 6258 NFS4ERR_BAD_SEQID 6259 NFS4ERR_EXPIRED 6260 NFS4ERR_FHEXPIRED 6261 NFS4ERR_GRACE 6262 NFS4ERR_INVAL 6263 NFS4ERR_MOVED 6264 NFS4ERR_NOENT 6265 NFS4ERR_NOFILEHANDLE 6266 NFS4ERR_NOTSUPP 6267 NFS4ERR_RESOURCE 6268 NFS4ERR_SERVERFAULT 6269 NFS4ERR_STALE 6270 NFS4ERR_WRONGSEC 6272 Draft Specification NFS version 4 Protocol December 1999 6274 14.2.19. Operation 21: PUTFH - Set Current Filehandle 6276 SYNOPSIS 6278 filehandle -> (cfh) 6280 ARGUMENT 6282 struct PUTFH4args { 6283 nfs4_fh object; 6284 }; 6286 RESULT 6288 struct PUTFH4res { 6289 /* CURRENT_FH: */ 6290 nfsstat4 status; 6291 }; 6293 DESCRIPTION 6295 Replaces the current filehandle with the filehandle provided as an 6296 argument. 6298 IMPLEMENTATION 6300 Commonly used as the first operator in any NFS request to set the 6301 context for following operations. 6303 ERRORS 6305 NFS4ERR_BADHANDLE 6306 NFS4ERR_FHEXPIRED 6307 NFS4ERR_MOVED 6308 NFS4ERR_RESOURCE 6309 NFS4ERR_SERVERFAULT 6310 NFS4ERR_STALE 6311 NFS4ERR_WRONGSEC 6313 Draft Specification NFS version 4 Protocol December 1999 6315 14.2.20. Operation 22: PUTPUBFH - Set Public Filehandle 6317 SYNOPSIS 6319 - -> (cfh) 6321 ARGUMENT 6323 void; 6325 RESULT 6327 struct PUTPUBFH4res { 6328 /* CURRENT_FH: root fh */ 6329 nfsstat4 status; 6330 }; 6332 DESCRIPTION 6334 Replaces the current filehandle with the filehandle that represents 6335 the public filehandle of the server's name space. This filehandle 6336 may be different from the "root" filehandle which may be associated 6337 with some other directory on the server. 6339 IMPLEMENTATION 6341 Used as the first operator in any NFS request to set the context 6342 for following operations. 6344 ERRORS 6346 NFS4ERR_RESOURCE 6347 NFS4ERR_SERVERFAULT 6348 NFS4ERR_WRONGSEC 6350 Draft Specification NFS version 4 Protocol December 1999 6352 14.2.21. Operation 23: PUTROOTFH - Set Root Filehandle 6354 SYNOPSIS 6356 - -> (cfh) 6358 ARGUMENT 6360 void; 6362 RESULT 6364 struct PUTROOTFH4res { 6365 /* CURRENT_FH: root fh */ 6366 nfsstat4 status; 6367 }; 6369 DESCRIPTION 6371 Replaces the current filehandle with the filehandle that represents 6372 the root of the server's name space. From this filehandle a LOOKUP 6373 operation can locate any other filehandle on the server. This 6374 filehandle may be different from the "public" filehandle which may 6375 be associated with some other directory on the server. 6377 IMPLEMENTATION 6379 Commonly used as the first operator in any NFS request to set the 6380 context for following operations. 6382 ERRORS 6384 NFS4ERR_RESOURCE 6385 NFS4ERR_SERVERFAULT 6386 NFS4ERR_WRONGSEC 6388 Draft Specification NFS version 4 Protocol December 1999 6390 14.2.22. Operation 24: READ - Read from File 6392 SYNOPSIS 6394 (cfh), offset, count, stateid -> eof, data 6396 ARGUMENT 6398 struct READ4args { 6399 /* CURRENT_FH: file */ 6400 stateid4 stateid; 6401 offset4 offset; 6402 count4 count; 6403 }; 6405 RESULT 6407 struct READ4resok { 6408 bool eof; 6409 opaque data<>; 6410 }; 6412 union READ4res switch (nfsstat4 status) { 6413 case NFS4_OK: 6414 READ4resok resok4; 6415 default: 6416 void; 6417 }; 6419 DESCRIPTION 6421 The READ operation reads data from the regular file identified by 6422 the current filehandle. 6424 The client provides an offset of where the READ is to start and a 6425 count of how many bytes are to be read. An offset of 0 (zero) 6426 means to read data starting at the beginning of the file. If 6427 offset is greater than or equal to the size of the file, the 6428 status, NFS4_OK, is returned with a data length set to 0 (zero) and 6429 eof set to TRUE. The READ is subject to access permissions 6430 checking. 6432 If the client specifies a count value of 0 (zero), the READ 6433 succeeds and returns 0 (zero) bytes of data again subject to access 6434 permissions checking. The server may choose to return fewer bytes 6436 Draft Specification NFS version 4 Protocol December 1999 6438 than specified by the client. The client needs to check for this 6439 condition and handle the condition appropriately. 6441 The stateid value for a READ request represents a value returned 6442 from a previous record lock or share reservation request. Used by 6443 the server to verify that the associated lock is still valid and to 6444 update lease timeouts for the client. 6446 If the read ended at the end-of-file (formally, in a correctly 6447 formed READ request, if offset + count is equal to the size of the 6448 file), eof is returned as TRUE; otherwise it is FALSE. A successful 6449 READ of an empty file will always return eof as TRUE. 6451 IMPLEMENTATION 6453 It is possible for the server to return fewer than count bytes of 6454 data. If the server returns less than the count requested and eof 6455 set to FALSE, the client should issue another READ to get the 6456 remaining data. A server may return less data than requested under 6457 several circumstances. The file may have been truncated by another 6458 client or perhaps on the server itself, changing the file size from 6459 what the requesting client believes to be the case. This would 6460 reduce the actual amount of data available to the client. It is 6461 possible that the server may back off the transfer size and reduce 6462 the read request return. Server resource exhaustion may also occur 6463 necessitating a smaller read return. 6465 If the file is locked the server will return an NFS4ERR_LOCKED 6466 error. Since the lock may be of short duration, the client may 6467 choose to retransmit the READ request (with exponential backoff) 6468 until the operation succeeds. 6470 ERRORS 6472 NFS4ERR_ACCES NFS4ERR_BADHANDLE NFS4ERR_BAD_STATEID NFS4ERR_DENIED 6473 NFS4ERR_EXPIRED NFS4ERR_FHEXPIRED NFS4ERR_GRACE NFS4ERR_INVAL 6474 NFS4ERR_IO NFS4ERR_JUKEBOX NFS4ERR_LOCKED NFS4ERR_MOVED 6475 NFS4ERR_NOFILEHANDLE NFS4ERR_NOT_CONFIRMED NFS4ERR_NXIO 6476 NFS4ERR_OLD_STATEID NFS4ERR_RESOURCE NFS4ERR_SERVERFAULT 6477 NFS4ERR_STALE NFS4ERR_STALE_STATEID NFS4ERR_WRONGSEC 6479 Draft Specification NFS version 4 Protocol December 1999 6481 14.2.23. Operation 25: READDIR - Read Directory 6483 SYNOPSIS 6484 (cfh), cookie, cookieverf, dircount, maxcount, attrbits -> 6485 cookieverf { cookie, filename, attrbits, attributes } 6487 ARGUMENT 6489 struct READDIR4args { 6490 /* CURRENT_FH: directory */ 6491 nfs_cookie4 cookie; 6492 cookieverf4 cookieverf; 6493 count4 dircount; 6494 count4 maxcount; 6495 bitmap4 attr_request; 6496 }; 6498 RESULT 6500 struct entry4 { 6501 nfs_cookie4 cookie; 6502 component4 name; 6503 fattr4 attrs; 6504 entry4 *nextentry; 6505 }; 6507 struct dirlist4 { 6508 entry4 *entries; 6509 bool eof; 6510 }; 6512 struct READDIR4resok { 6513 cookieverf4 cookieverf; 6514 dirlist4 reply; 6515 }; 6517 union READDIR4res switch (nfsstat4 status) { 6518 case NFS4_OK: 6519 READDIR4resok resok4; 6520 default: 6521 void; 6522 }; 6524 DESCRIPTION 6526 Draft Specification NFS version 4 Protocol December 1999 6528 The READDIR operation retrieves a variable number of entries from a 6529 file system directory and returns client requested attributes for 6530 each entry along with information to allow the client to request 6531 additional directory entries in a subsequent READDIR. 6533 The arguments contain a cookie value that represents where the 6534 READDIR should start within the directory. A value of 0 (zero) for 6535 the cookie is used to start reading at the beginning of the 6536 directory. For subsequent READDIR requests, the client specifies a 6537 cookie value that is provided by the server on a previous READDIR 6538 request. 6540 The cookieverf value should be set to 0 (zero) when the cookie 6541 value is 0 (zero) (first directory read). On subsequent requests, 6542 it should be a cookieverf as returned by the server. The 6543 cookieverf must match that returned by the READDIR in which the 6544 cookie was acquired. 6546 The dircount portion of the argument is a hint of the maximum 6547 number of bytes of directory information that should be returned. 6548 This value is the XDR encoded length of the name of the directory 6549 entries and the cookie value for the entries. The server may 6550 return less data. 6552 The maxcount value of the argument is the maximum number of bytes 6553 for the result. This maximum size represents all of the data being 6554 returned and includes the XDR overhead. The server may return less 6555 data. If the server is unable to return a single directory entry 6556 within the maxcount limit, the error NFS4ERR_READDIR_NOSPC will be 6557 returned to the client. 6559 Finally, attrbits represents the list of attributes to be returned 6560 for each directory entry supplied by the server. 6562 On successful return, the server's response will provide a list of 6563 directory entries. Each of these entries contains the name of the 6564 directory entry, a cookie value for that entry, and the associated 6565 attributes as requested. 6567 The cookie value is only meaningful to the server and is used as a 6568 "bookmark" for the directory entry. As mentioned, this cookie is 6569 used by the client for subsequent READDIR operations so that it may 6570 continue reading a directory. The cookie is similar in concept to 6571 a READ offset but should not be interpreted as such by the client. 6572 Ideally, the cookie value should not change if the directory is 6573 modified. 6575 In some cases, the server may encounter an error while obtaining 6577 Draft Specification NFS version 4 Protocol December 1999 6579 the attributes for a directory entry. Instead of returning an 6580 error for the entire READDIR operation, the server can instead 6581 return the attribute 'fattr4_rdattr_error'. With this, the server 6582 is able to communicate the failure to the client and not fail the 6583 entire operation in the instance of what might be a transient 6584 failure. Obviously, the client must request the 6585 fattr4_rdattr_error attribute for this method to work properly. If 6586 the client does not request the attribute, the server has no choice 6587 but to return failure for the entire READDIR operation. 6589 For some file system environments, the directory entries "." and 6590 ".." have special meaning and in other environments, they may not. 6591 If the server supports these special entries within a directory, 6592 they should not be returned to the client as part of the READDIR 6593 response. To enable some client environments, the cookie values of 6594 0, 1, and 2 are to be considered reserved. For READDIR arguments, 6595 cookie values of 1 and 2 should not be used and for READDIR results 6596 cookie values of 0, 1, and 2 should not returned. 6598 IMPLEMENTATION 6600 The server's file system directory representations can differ 6601 greatly. A client's programming interfaces may also be bound to 6602 the local operating environment in a way that does not translate 6603 well into the NFS protocol. Therefore the use of the dircount and 6604 maxcount fields are provided to allow the client the ability to 6605 provide guidelines to the server. If the client is aggressive 6606 about attribute collection during a READDIR, the server has an idea 6607 of how to limit the encoded response. The dircount field provides 6608 a hint on the number of entries based solely on the names of the 6609 directory entries. 6611 The cookieverf may be used by the server to help manage cookie 6612 values that may become stale. It should be a rare occurrence that 6613 a server is unable to continue properly reading a directory with 6614 the provided cookie/cookieverf pair. The server should make every 6615 effort to avoid this condition since the application at the client 6616 may not be able to properly handle this type of failure. 6618 The use of the cookieverf will also protect the client from using 6619 READDIR cookie values that may be stale. For example, if the file 6620 system has been migrated, the server may or may not be able to use 6621 the same cookie values to service READDIR as the previous server 6622 used. With the client providing the cookieverf, the server is able 6623 to provide the appropriate response to the client. This prevents 6624 the case where the server may accept a cookie value but the 6625 underlying directory has changed and the response is invalid from 6627 Draft Specification NFS version 4 Protocol December 1999 6629 the client's context of its previous READDIR. 6631 ERRORS 6633 NFS4ERR_ACCES 6634 NFS4ERR_BADHANDLE 6635 NFS4ERR_BAD_COOKIE 6636 NFS4ERR_FHEXPIRED 6637 NFS4ERR_INVAL 6638 NFS4ERR_IO 6639 NFS4ERR_JUKEBOX 6640 NFS4ERR_MOVED 6641 NFS4ERR_NOFILEHANDLE 6642 NFS4ERR_NOTDIR 6643 NFS4ERR_NOTSUPP 6644 NFS4ERR_READDIR_NOSPC 6645 NFS4ERR_RESOURCE 6646 NFS4ERR_SERVERFAULT 6647 NFS4ERR_STALE 6648 NFS4ERR_TOOSMALL 6649 NFS4ERR_WRONGSEC 6651 Draft Specification NFS version 4 Protocol December 1999 6653 14.2.24. Operation 26: READLINK - Read Symbolic Link 6655 SYNOPSIS 6657 (cfh) -> linktext 6659 ARGUMENT 6661 /* CURRENT_FH: symlink */ 6662 void; 6664 RESULT 6666 struct READLINK4resok { 6667 linktext4 link; 6668 }; 6670 union READLINK4res switch (nfsstat4 status) { 6671 case NFS4_OK: 6672 READLINK4resok resok4; 6673 default: 6674 void; 6675 }; 6677 DESCRIPTION 6679 READLINK reads the data associated with a symbolic link. The data 6680 is a UTF-8 string that is opaque to the server. That is, whether 6681 created by an NFS client or created locally on the server, the data 6682 in a symbolic link is not interpreted when created, but is simply 6683 stored. 6685 IMPLEMENTATION 6687 A symbolic link is nominally a pointer to another file. The data 6688 is not necessarily interpreted by the server, just stored in the 6689 file. It is possible for a client implementation to store a path 6690 name that is not meaningful to the server operating system in a 6691 symbolic link. A READLINK operation returns the data to the client 6692 for interpretation. If different implementations want to share 6693 access to symbolic links, then they must agree on the 6694 interpretation of the data in the symbolic link. 6696 The READLINK operation is only allowed on objects of type, NF4LNK. 6698 Draft Specification NFS version 4 Protocol December 1999 6700 The server should return the error, NFS4ERR_INVAL, if the object is 6701 not of type, NF4LNK. 6703 ERRORS 6705 NFS4ERR_ACCES 6706 NFS4ERR_BADHANDLE 6707 NFS4ERR_FHEXPIRED 6708 NFS4ERR_INVAL 6709 NFS4ERR_IO 6710 NFS4ERR_JUKEBOX 6711 NFS4ERR_MOVED 6712 NFS4ERR_NOTSUPP 6713 NFS4ERR_RESOURCE 6714 NFS4ERR_SERVERFAULT 6715 NFS4ERR_STALE 6716 NFS4ERR_WRONGSEC 6718 Draft Specification NFS version 4 Protocol December 1999 6720 14.2.25. Operation 27: REMOVE - Remove Filesystem Object 6722 SYNOPSIS 6724 (cfh), filename -> change_info 6726 ARGUMENT 6728 struct REMOVE4args { 6729 /* CURRENT_FH: directory */ 6730 component4 target; 6731 }; 6733 RESULT 6735 struct REMOVE4resok { 6736 change_info4 cinfo; 6737 } 6739 union REMOVE4res switch (nfsstat4 status) { 6740 case NFS4_OK: 6741 REMOVE4resok resok4; 6742 default: 6743 void; 6744 } 6746 DESCRIPTION 6748 The REMOVE operation removes (deletes) a directory entry named by 6749 filename from the directory corresponding to the current 6750 filehandle. If the entry in the directory was the last reference 6751 to the corresponding file system object, the object may be 6752 destroyed. 6754 For the directory where the filename was removed, the server 6755 returns change_info4 information in cinfo. With the atomic field 6756 of the change_info4 struct, the server will indicate if the before 6757 and after change attributes were obtained atomically with respect 6758 to the removal. 6760 IMPLEMENTATION 6762 NFS versions 2 and 3 required a different operator RMDIR for 6763 directory removal. NFS version 4 REMOVE can be used to delete any 6765 Draft Specification NFS version 4 Protocol December 1999 6767 directory entry independent of its file type. 6769 The concept of last reference is server specific. However, if the 6770 numlinks field in the previous attributes of the object had the 6771 value 1, the client should not rely on referring to the object via 6772 a file handle. Likewise, the client should not rely on the 6773 resources (disk space, directory entry, and so on.) formerly 6774 associated with the object becoming immediately available. Thus, if 6775 a client needs to be able to continue to access a file after using 6776 REMOVE to remove it, the client should take steps to make sure that 6777 the file will still be accessible. The usual mechanism used is to 6778 use RENAME to rename the file from its old name to a new hidden 6779 name. 6781 ERRORS 6783 NFS4ERR_ACCES 6784 NFS4ERR_BADHANDLE 6785 NFS4ERR_FHEXPIRED 6786 NFS4ERR_IO 6787 NFS4ERR_MOVED 6788 NFS4ERR_NAMETOOLONG 6789 NFS4ERR_NOENT 6790 NFS4ERR_NOFILEHANDLE 6791 NFS4ERR_NOTDIR 6792 NFS4ERR_NOTEMPTY 6793 NFS4ERR_NOTSUPP 6794 NFS4ERR_RESOURCE 6795 NFS4ERR_ROFS 6796 NFS4ERR_SERVERFAULT 6797 NFS4ERR_STALE 6798 NFS4ERR_WRONGSEC 6800 Draft Specification NFS version 4 Protocol December 1999 6802 14.2.26. Operation 28: RENAME - Rename Directory Entry 6804 SYNOPSIS 6806 (sfh), oldname (cfh), newname -> source_change_info, 6807 target_change_info 6809 ARGUMENT 6811 struct RENAME4args { 6812 /* SAVED_FH: source directory */ 6813 component4 oldname; 6814 /* CURRENT_FH: target directory */ 6815 component4 newname; 6816 }; 6818 RESULT 6820 struct RENAME4resok { 6821 change_info4 source_cinfo; 6822 change_info4 target_cinfo; 6823 }; 6825 union RENAME4res switch (nfsstat4 status) { 6826 case NFS4_OK: 6827 RENAME4resok resok4; 6828 default: 6829 void; 6830 }; 6832 DESCRIPTION 6834 The RENAME operation renames the object identified by oldname in 6835 the source directory corresponding to the saved filehandle to 6836 newname in the target directory corresponding to the current 6837 filehandle. The operation is required to be atomic to the client. 6838 Source and target directories must reside on the same file system 6839 on the server. 6841 If the target directory already contains an entry with the name, 6842 newname, the source object must be compatible with the target: 6843 either both are non-directories or both are directories and the 6844 target must be empty. If compatible, the existing target is 6845 removed before the rename occurs. If they are not compatible or if 6846 the target is a directory but not empty, the server will return the 6848 Draft Specification NFS version 4 Protocol December 1999 6850 error, NFS4ERR_EXIST. 6852 If oldname and newname both refer to the same file (they might be 6853 hard links of each other), then RENAME should perform no action and 6854 return success. 6856 For both directories involved in the RENAME, the server returns 6857 change_info4 information. With the atomic field of the 6858 change_info4 struct, the server will indicate if the before and 6859 after change attributes were obtained atomically with respect to 6860 the rename. 6862 IMPLEMENTATION 6864 The RENAME operation must be atomic to the client. The statement 6865 "source and target directories must reside on the same file system 6866 on the server" means that the fsid fields in the attributes for the 6867 directories are the same. If they reside on different file systems, 6868 the error, NFS4ERR_XDEV, is returned. Even though the operation is 6869 atomic, the status, NFS4ERR_MLINK, may be returned if the server 6870 used a "unlink/link/unlink" sequence internally. 6872 A filehandle may or may not become stale or expire on a rename. 6873 However, server implementors are strongly encouraged to attempt to 6874 keep file handles from becoming stale or expiring in this fashion. 6876 On some servers, the filenames, "." and "..", are illegal as either 6877 oldname or newname. In addition, neither oldname nor newname can 6878 be an alias for the source directory. These servers will return 6879 the error, NFS4ERR_INVAL, in these cases. 6881 ERRORS 6883 NFS4ERR_ACCES 6884 NFS4ERR_BADHANDLE 6885 NFS4ERR_DQUOT 6886 NFS4ERR_EXIST 6887 NFS4ERR_FHEXPIRED 6888 NFS4ERR_INVAL 6889 NFS4ERR_IO 6890 NFS4ERR_ISDIR 6891 NFS4ERR_MLINK 6892 NFS4ERR_MOVED 6893 NFS4ERR_NAMETOOLONG 6894 NFS4ERR_NOENT 6896 Draft Specification NFS version 4 Protocol December 1999 6898 NFS4ERR_NOFILEHANDLE 6899 NFS4ERR_NOSPC 6900 NFS4ERR_NOTDIR 6901 NFS4ERR_NOTEMPTY 6902 NFS4ERR_NOTSUPP 6903 NFS4ERR_RESOURCE 6904 NFS4ERR_ROFS 6905 NFS4ERR_SERVERFAULT 6906 NFS4ERR_STALE 6907 NFS4ERR_WRONGSEC 6908 NFS4ERR_XDEV 6910 Draft Specification NFS version 4 Protocol December 1999 6912 14.2.27. Operation 29: RENEW - Renew a Lease 6914 SYNOPSIS 6916 stateid -> () 6918 ARGUMENT 6920 struct RENEW4args { 6921 stateid4 stateid; 6922 }; 6924 RESULT 6926 struct RENEW4res { 6927 nfsstat4 status; 6928 }; 6930 DESCRIPTION 6932 The RENEW operation is used by the client to renew leases which it 6933 currently holds at a server. In processing the RENEW request, the 6934 server renews all leases associated with the client. The 6935 associated leases are determined by the client id provided via the 6936 SETCLIENTID procedure. 6938 The stateid for RENEW may not be one of the special stateids 6939 consisting of all bits 0 (zero) or all bits 1. 6941 IMPLEMENTATION 6943 ERRORS 6945 NFS4ERR_BAD_STATEID 6946 NFS4ERR_EXPIRED 6947 NFS4ERR_GRACE 6948 NFS4ERR_INVAL 6949 NFS4ERR_MOVED 6950 NFS4ERR_OLD_STATEID 6951 NFS4ERR_RESOURCE 6952 NFS4ERR_SERVERFAULT 6953 NFS4ERR_STALE_STATEID 6955 Draft Specification NFS version 4 Protocol December 1999 6957 NFS4ERR_WRONGSEC 6959 Draft Specification NFS version 4 Protocol December 1999 6961 14.2.28. Operation 30: RESTOREFH - Restore Saved Filehandle 6963 SYNOPSIS 6965 (sfh) -> (cfh) 6967 ARGUMENT 6969 /* SAVED_FH: */ 6970 void; 6972 RESULT 6974 struct RESTOREFH4res { 6975 /* CURRENT_FH: value of saved fh */ 6976 nfsstat4 status; 6977 }; 6979 DESCRIPTION 6981 Set the current filehandle to the value in the saved filehandle. 6982 If there is no saved filehandle then return an error NFS4ERR_INVAL. 6984 IMPLEMENTATION 6986 Operations like OPEN and LOOKUP use the current filehandle to 6987 represent a directory and replace it with a new filehandle. 6988 Assuming the previous filehandle was saved with a SAVEFH operator, 6989 the previous filehandle can be restored as the current filehandle. 6990 This is commonly used to obtain post-operation attributes for the 6991 directory, e.g. 6993 PUTFH (directory filehandle) 6994 SAVEFH 6995 GETATTR attrbits (pre-op dir attrs) 6996 CREATE optbits "foo" attrs 6997 GETATTR attrbits (file attributes) 6998 RESTOREFH 6999 GETATTR attrbits (post-op dir attrs) 7001 ERRORS 7003 Draft Specification NFS version 4 Protocol December 1999 7005 NFS4ERR_BADHANDLE 7006 NFS4ERR_FHEXPIRED 7007 NFS4ERR_MOVED 7008 NFS4ERR_NOFILEHANDLE 7009 NFS4ERR_RESOURCE 7010 NFS4ERR_SERVERFAULT 7011 NFS4ERR_STALE 7012 NFS4ERR_WRONGSEC 7014 Draft Specification NFS version 4 Protocol December 1999 7016 14.2.29. Operation 31: SAVEFH - Save Current Filehandle 7018 SYNOPSIS 7020 (cfh) -> (sfh) 7022 ARGUMENT 7024 /* CURRENT_FH: */ 7025 void; 7027 RESULT 7029 struct SAVEFH4res { 7030 /* SAVED_FH: value of current fh */ 7031 nfsstat4 status; 7032 }; 7034 DESCRIPTION 7036 Save the current filehandle. If a previous filehandle was saved 7037 then it is no longer accessible. The saved filehandle can be 7038 restored as the current filehandle with the RESTOREFH operator. 7040 On success, the current filehandle retains its value. 7042 IMPLEMENTATION 7044 ERRORS 7046 NFS4ERR_BADHANDLE 7047 NFS4ERR_FHEXPIRED 7048 NFS4ERR_MOVED 7049 NFS4ERR_NOFILEHANDLE 7050 NFS4ERR_RESOURCE 7051 NFS4ERR_SERVERFAULT 7052 NFS4ERR_STALE 7053 NFS4ERR_WRONGSEC 7055 Draft Specification NFS version 4 Protocol December 1999 7057 14.2.30. Operation 32: SECINFO - Obtain Available Security 7059 SYNOPSIS 7061 (cfh), name -> { secinfo } 7063 ARGUMENT 7065 struct SECINFO4args { 7066 /* CURRENT_FH: */ 7067 component4 name; 7068 }; 7070 RESULT 7072 enum rpc_gss_svc_t { 7073 RPC_GSS_SVC_NONE = 1, 7074 RPC_GSS_SVC_INTEGRITY = 2, 7075 RPC_GSS_SVC_PRIVACY = 3 7076 }; 7078 struct rpcsec_gss_info { 7079 sec_oid4 oid; 7080 qop4 qop; 7081 rpc_gss_svc_t service; 7082 }; 7084 struct secinfo4 { 7085 uint32_t flavor; 7086 opaque flavor_info<>; /* null for AUTH_SYS, AUTH_NONE; 7087 contains rpcsec_gss_info for 7088 RPCSEC_GSS. */ 7089 }; 7091 typedef secinfo4 SECINFO4resok<>; 7093 union SECINFO4res switch (nfsstat4 status) { 7094 case NFS4_OK: 7095 SECINFO4resok resok4; 7096 default: 7097 void; 7098 }; 7100 DESCRIPTION 7102 Draft Specification NFS version 4 Protocol December 1999 7104 The SECINFO operation is used by the client to obtain a list of 7105 valid RPC authentication flavors for a specific file handle, file 7106 name pair. The result will contain an array which represents the 7107 security mechanisms available. The array entries are represented 7108 by the secinfo4 structure. The field 'flavor' will contain a value 7109 of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or RPCSEC_GSS (as 7110 defined in [RFC2203]). 7112 For the flavors, AUTH_NONE, and AUTH_SYS no additional security 7113 information is returned. For a return value of RPCSEC_GSS, a 7114 security triple is returned that contains the mechanism object id 7115 (as defined in [RFC2078]), the quality of protection (as defined in 7116 [RFC2078]) and the service type (as defined in [RFC2203]). It is 7117 possible for SECINFO to return multiple entries with flavor equal 7118 to RPCSEC_GSS with different security triple values. 7120 IMPLEMENTATION 7122 The SECINFO operation is expected to be used by the NFS client when 7123 the error value of NFS4ERR_WRONGSEC is returned from another NFS 7124 operation. This signifies to the client that the server's security 7125 policy is different from what the client is currently using. At 7126 this point, the client is expected to obtain a list of possible 7127 security flavors and choose what best suits its policies. 7129 It is recommended that the client issue the SECINFO call protected 7130 by a security triple that uses either rpc_gss_svc_integrity or 7131 rpc_gss_svc_privacy service. The use of rpc_gss_svc_none would 7132 allow an attacker in the middle to modify the SECINFO results such 7133 that the client might select a weaker algorithm in the set allowed 7134 by server, making the client and/or server vulnerable to further 7135 attacks. 7137 ERRORS 7139 NFS4ERR_BADHANDLE 7140 NFS4ERR_FHEXPIRED 7141 NFS4ERR_MOVED 7142 NFS4ERR_NAMETOOLONG 7143 NFS4ERR_NOENT 7144 NFS4ERR_NOFILEHANDLE 7145 NFS4ERR_NOTDIR 7146 NFS4ERR_RESOURCE 7147 NFS4ERR_SERVERFAULT 7148 NFS4ERR_STALE 7149 NFS4ERR_WRONGSEC 7151 Draft Specification NFS version 4 Protocol December 1999 7153 14.2.31. Operation 33: SETATTR - Set Attributes 7155 SYNOPSIS 7157 (cfh), attrbits, attrvals -> - 7159 ARGUMENT 7161 struct SETATTR4args { 7162 /* CURRENT_FH: target object */ 7163 stateid4 stateid; 7164 fattr4 obj_attributes; 7165 }; 7167 RESULT 7169 struct SETATTR4res { 7170 nfsstat4 status; 7171 bitmap4 attrsset; 7172 }; 7174 DESCRIPTION 7176 The SETATTR operation changes one or more of the attributes of a 7177 file system object. The new attributes are specified with a bitmap 7178 and the attributes that follow the bitmap in bit order. 7180 The stateid is necessary for SETATTRs that change the size of file 7181 (modify the attribute object_size). This stateid represents a 7182 record lock, share reservation, or delegation which must be valid 7183 for the SETATTR to modify the file data. 7185 On either success or failure of the operation, the server will 7186 return the attrsset bitmask to represent what (if any) attributes 7187 were successfully set. 7189 IMPLEMENTATION 7191 The file size attribute is used to request changes to the size of a 7192 file. A value of 0 (zero) causes the file to be truncated, a value 7193 less than the current size of the file causes data from new size to 7194 the end of the file to be discarded, and a size greater than the 7195 current size of the file causes logically zeroed data bytes to be 7196 added to the end of the file. Servers are free to implement this 7198 Draft Specification NFS version 4 Protocol December 1999 7200 using holes or actual zero data bytes. Clients should not make any 7201 assumptions regarding a server's implementation of this feature, 7202 beyond that the bytes returned will be zeroed. Servers must 7203 support extending the file size via SETATTR. 7205 SETATTR is not guaranteed atomic. A failed SETATTR may partially 7206 change a file's attributes. 7208 Changing the size of a file with SETATTR indirectly changes the 7209 time_modify. A client must account for this as size changes can 7210 result in data deletion. 7212 If server and client times differ, programs that compare client 7213 time to file times can break. A time maintenance protocol should be 7214 used to limit client/server time skew. 7216 If the server cannot successfully set all the attributes it must 7217 return an NFS4ERR_INVAL error. If the server can only support 32 7218 bit offsets and sizes, a SETATTR request to set the size of a file 7219 to larger than can be represented in 32 bits will be rejected with 7220 this same error. 7222 ERRORS 7224 NFS4ERR_ACCES 7225 NFS4ERR_BADHANDLE 7226 NFS4ERR_DENIED 7227 NFS4ERR_DQUOT 7228 NFS4ERR_EXPIRED 7229 NFS4ERR_FBIG 7230 NFS4ERR_FHEXPIRED 7231 NFS4ERR_GRACE 7232 NFS4ERR_INVAL 7233 NFS4ERR_IO 7234 NFS4ERR_JUKEBOX 7235 NFS4ERR_MOVED 7236 NFS4ERR_NOFILEHANDLE 7237 NFS4ERR_NOSPC 7238 NFS4ERR_NOTSUPP 7239 NFS4ERR_PERM 7240 NFS4ERR_RESOURCE 7241 NFS4ERR_ROFS 7242 NFS4ERR_SERVERFAULT 7243 NFS4ERR_STALE 7244 NFS4ERR_WRONGSEC 7246 Draft Specification NFS version 4 Protocol December 1999 7248 14.2.32. Operation 34: SETCLIENTID - Negotiate Clientid 7250 SYNOPSIS 7252 seqid, client, callback -> clientid 7254 ARGUMENT 7256 struct SETCLIENTID4args { 7257 seqid4 seqid; 7258 bool confirm; 7259 nfs_client_id4 client; 7260 cb_client4 callback; 7261 }; 7263 RESULT 7265 struct SETCLIENTID4resok { 7266 clientid4 clientid; 7267 cookieverf4 setclientid_confirm; 7268 }; 7270 union SETCLIENTID4res switch (nfsstat4 status) { 7271 case NFS4_OK: 7272 SETCLIENTID4resok resok4; 7273 case NFS4ERR_CLID_INUSE: 7274 clientaddr4 client_using; 7275 default: 7276 void; 7277 }; 7279 DESCRIPTION 7281 The SETCLIENTID operation introduces the ability of the client to 7282 notify the server of its intention to use a particular client 7283 identifier and verifier pair. Upon successful completion the 7284 server will return a clientid which is used in subsequent file 7285 locking requests. The client may request a confirmation of the 7286 SETCLIENTID operation by setting the confirm argument field to 7287 TRUE. The server will then return a confirmation cookie. The 7288 client will use the SETCLIENTID_CONFIRM operation to return the 7289 cookie and the next sequence id to the server. 7291 The callback information provided in this operation will be used if 7292 the client is granted a open delegation at a future point. 7294 Draft Specification NFS version 4 Protocol December 1999 7296 Therefore, the client must correctly reflect the program and port 7297 numbers for the callback program at the time SETCLIENTID is used. 7299 IMPLEMENTATION 7301 The server takes the verifier and client identification supplied 7302 and searches for a match of the client identification. If no match 7303 is found the server saves the principal/uid information along with 7304 the verifier and client identification and returns a unique 7305 clientid that is used as a shorthand reference to the supplied 7306 information. 7308 If the server finds matching client identification and a 7309 corresponding match in principal/uid, the server releases all 7310 locking state for the client and returns a new clientid. 7312 The principal or principal to user identifier mapping is taken from 7313 the credential presented in the RPC. As mentioned, the server will 7314 use the credential and associated principal for the matching with 7315 existing clientids. If the client is a traditional host based 7316 client like a Unix NFS client, then the credential presented may be 7317 the host credential. If the client is a user level client or light 7318 weight client, the credential used may be the end user's 7319 credential. The client should take care in choosing an appropriate 7320 credential since denial of service attacks could be attempted by a 7321 rogue client that has access to the credential. 7323 ERRORS 7325 NFS4ERR_CLID_INUSE 7326 NFS4ERR_INVAL 7327 NFS4ERR_RESOURCE 7328 NFS4ERR_SERVERFAULT 7330 Draft Specification NFS version 4 Protocol December 1999 7332 14.2.33. Operation 35: SETCLIENTID_CONFIRM - Confirm Clientid 7334 SYNOPSIS 7336 seqid, setclientid_confirm -> - 7338 ARGUMENT 7340 struct SETCLIENTID_CONFIRM4args { 7341 seqid4seqid; 7342 cookieverf4setclientid_confirm; 7343 }; 7345 RESULT 7347 struct SETCLIENTID_CONFIRM4res { 7348 nfsstat4status; 7349 }; 7351 DESCRIPTION 7353 This operation is used by the client to confirm the results from a 7354 previous call to SETCLIENTID. The client provides a sequence id 7355 that is 1 (one) greater than the sequence id provided with the 7356 corresponding SETCLIENTID operation. The client also provides the 7357 server supplied opaque confirmation cookie. The server responds 7358 with a simple status of success or failure. 7360 IMPLEMENTATION 7362 The SETCLIENTID_CONFIRM operation is optional and its use is 7363 determined by the client when it sends the initial SETCLIENTID 7364 operation to the server. If the server is told that the client 7365 wants to confirm the SETCLIENTID operation, then all state 7366 previously held by the client (if applicable) is held until the 7367 receipt of the SETCLIENTID_CONFIRM is successful. The server 7368 should choose a confirmation cookie value that is reasonably unique 7369 for the client. 7371 ERRORS 7373 NFS4ERR_CLID_INUSE 7374 NFS4ERR_INVAL 7376 Draft Specification NFS version 4 Protocol December 1999 7378 NFS4ERR_RESOURCE 7379 NFS4ERR_SERVERFAULT 7381 Draft Specification NFS version 4 Protocol December 1999 7383 14.2.34. Operation 36: VERIFY - Verify Same Attributes 7385 SYNOPSIS 7387 (cfh), attrbits, attrvals -> - 7389 ARGUMENT 7391 struct VERIFY4args { 7392 /* CURRENT_FH: object */ 7393 bitmap4 attr_request; 7394 fattr4 obj_attributes; 7395 }; 7397 RESULT 7399 struct VERIFY4res { 7400 nfsstat4 status; 7401 }; 7403 DESCRIPTION 7405 The VERIFY operation is used to verify that attributes have a value 7406 assumed by the client before proceeding with following operations 7407 in the compound request. The current filehandle retains its value 7408 after successful completion of the operation. 7410 IMPLEMENTATION 7412 One possible use of the VERIFY operation is the following compound 7413 sequence. With this the client is attempting to verify that the 7414 file being removed will match what the client expects to be 7415 removed. This sequence can help prevent the unintended deletion of 7416 a file. 7418 PUTFH (directory filehandle) 7419 LOOKUP (file name) 7420 VERIFY (filehandle == fh) 7421 PUTFH (directory filehandle) 7422 REMOVE (file name) 7424 This sequence does not prevent a second client from removing and 7425 creating a new file in the middle of this sequence but it does help 7426 avoid the unintended result. 7428 Draft Specification NFS version 4 Protocol December 1999 7430 ERRORS 7432 NFS4ERR_ACCES 7433 NFS4ERR_BADHANDLE 7434 NFS4ERR_FHEXPIRED 7435 NFS4ERR_INVAL 7436 NFS4ERR_JUKEBOX 7437 NFS4ERR_MOVED 7438 NFS4ERR_NOFILEHANDLE 7439 NFS4ERR_NOTSUPP 7440 NFS4ERR_RESOURCE 7441 NFS4ERR_SERVERFAULT 7442 NFS4ERR_STALE 7443 NFS4ERR_WRONGSEC 7445 Draft Specification NFS version 4 Protocol December 1999 7447 14.2.35. Operation 37: WRITE - Write to File 7449 SYNOPSIS 7451 (cfh), offset, count, stability, stateid, data -> count, committed, 7452 verifier 7454 ARGUMENT 7456 enum stable_how4 { 7457 UNSTABLE4 = 0, 7458 DATA_SYNC4 = 1, 7459 FILE_SYNC4 = 2 7460 }; 7462 struct WRITE4args { 7463 /* CURRENT_FH: file */ 7464 stateid4 stateid; 7465 offset4 offset; 7466 stable_how4 stable; 7467 opaque data<>; 7468 }; 7470 RESULT 7472 struct WRITE4resok { 7473 count4 count; 7474 stable_how4 committed; 7475 writeverf4 verf; 7476 }; 7478 union WRITE4res switch (nfsstat4 status) { 7479 case NFS4_OK: 7480 WRITE4resok resok4; 7481 default: 7482 void; 7483 }; 7485 DESCRIPTION 7487 The WRITE operation is used to write data to a regular file. The 7488 target file is specified by the current filehandle. The offset 7489 specifies the offset where the data should be written. An offset 7490 of 0 (zero) specifies that the write should start at the beginning 7491 of the file. The count represents the number of bytes of data that 7493 Draft Specification NFS version 4 Protocol December 1999 7495 are to be written. If the count is 0 (zero), the WRITE will 7496 succeed and return a count of 0 (zero) subject to permissions 7497 checking. The server may choose to write fewer bytes than 7498 requested by the client. 7500 Part of the write request is a specification of how the write is to 7501 be performed. The client specifies with the stable parameter the 7502 method of how the data is to be processed by the server. If stable 7503 is FILE_SYNC4, the server must commit the data written plus all 7504 file system metadata to stable storage before returning results. 7505 This corresponds to the NFS version 2 protocol semantics. Any 7506 other behavior constitutes a protocol violation. If stable is 7507 DATA_SYNC4, then the server must commit all of the data to stable 7508 storage and enough of the metadata to retrieve the data before 7509 returning. The server implementor is free to implement DATA_SYNC4 7510 in the same fashion as FILE_SYNC4, but with a possible performance 7511 drop. If stable is UNSTABLE4, the server is free to commit any 7512 part of the data and the metadata to stable storage, including all 7513 or none, before returning a reply to the client. There is no 7514 guarantee whether or when any uncommitted data will subsequently be 7515 committed to stable storage. The only guarantees made by the server 7516 are that it will not destroy any data without changing the value of 7517 verf and that it will not commit the data and metadata at a level 7518 less than that requested by the client. 7520 The stateid returned from a previous record lock or share 7521 reservation request is provided as part of the argument. The 7522 stateid is used by the server to verify that the associated lock is 7523 still valid and to update lease timeouts for the client. 7525 Upon successful completion, the following results are returned. 7526 The count result is the number of bytes of data written to the 7527 file. The server may write fewer bytes than requested. If so, the 7528 actual number of bytes written starting at location, offset, is 7529 returned. 7531 The server also returns an indication of the level of commitment of 7532 the data and metadata via committed. If the server committed all 7533 data and metadata to stable storage, committed should be set to 7534 FILE_SYNC4. If the level of commitment was at least as strong as 7535 DATA_SYNC4, then committed should be set to DATA_SYNC4. Otherwise, 7536 committed must be returned as UNSTABLE4. If stable was FILE4_SYNC, 7537 then committed must also be FILE_SYNC4: anything else constitutes a 7538 protocol violation. If stable was DATA_SYNC4, then committed may be 7539 FILE_SYNC4 or DATA_SYNC4: anything else constitutes a protocol 7540 violation. If stable was UNSTABLE4, then committed may be either 7541 FILE_SYNC4, DATA_SYNC4, or UNSTABLE4. 7543 Draft Specification NFS version 4 Protocol December 1999 7545 The final portion of the result is the write verifier, verf. The 7546 write verifier is a cookie that the client can use to determine 7547 whether the server has changed state between a call to WRITE and a 7548 subsequent call to either WRITE or COMMIT. This cookie must be 7549 consistent during a single instance of the NFS version 4 protocol 7550 service and must be unique between instances of the NFS version 4 7551 protocol server, where uncommitted data may be lost. 7553 If a client writes data to the server with the stable argument set 7554 to UNSTABLE4 and the reply yields a committed response of 7555 DATA_SYNC4 or UNSTABLE4, the client will follow up some time in the 7556 future with a COMMIT operation to synchronize outstanding 7557 asynchronous data and metadata with the server's stable storage, 7558 barring client error. It is possible that due to client crash or 7559 other error that a subsequent COMMIT will not be received by the 7560 server. 7562 On success, the current filehandle retains its value. 7564 IMPLEMENTATION 7566 It is possible for the server to write fewer than count bytes of 7567 data. In this case, the server should not return an error unless 7568 no data was written at all. If the server writes less than count 7569 bytes, the client should issue another WRITE to write the remaining 7570 data. 7572 It is assumed that the act of writing data to a file will cause the 7573 time_modified of the file to be updated. However, the 7574 time_modified of the file should not be changed unless the contents 7575 of the file are changed. Thus, a WRITE request with count set to 0 7576 should not cause the time_modified of the file to be updated. 7578 The definition of stable storage has been historically a point of 7579 contention. The following expected properties of stable storage 7580 may help in resolving design issues in the implementation. Stable 7581 storage is persistent storage that survives: 7583 1. Repeated power failures. 7584 2. Hardware failures (of any board, power supply, etc.). 7585 3. Repeated software crashes, including reboot cycle. 7587 This definition does not address failure of the stable storage 7588 module itself. 7590 Draft Specification NFS version 4 Protocol December 1999 7592 The verifier is defined to allow a client to detect different 7593 instances of an NFS version 4 protocol server over which cached, 7594 uncommitted data may be lost. In the most likely case, the verifier 7595 allows the client to detect server reboots. This information is 7596 required so that the client can safely determine whether the server 7597 could have lost cached data. If the server fails unexpectedly and 7598 the client has uncommitted data from previous WRITE requests (done 7599 with the stable argument set to UNSTABLE4 and in which the result 7600 committed was returned as UNSTABLE4 as well) it may not have 7601 flushed cached data to stable storage. The burden of recovery is on 7602 the client and the client will need to retransmit the data to the 7603 server. 7605 A suggested verifier would be to use the time that the server was 7606 booted or the time the server was last started (if restarting the 7607 server without a reboot results in lost buffers). 7609 The committed field in the results allows the client to do more 7610 effective caching. If the server is committing all WRITE requests 7611 to stable storage, then it should return with committed set to 7612 FILE_SYNC4, regardless of the value of the stable field in the 7613 arguments. A server that uses an NVRAM accelerator may choose to 7614 implement this policy. The client can use this to increase the 7615 effectiveness of the cache by discarding cached data that has 7616 already been committed on the server. 7618 Some implementations may return NFS4ERR_NOSPC instead of 7619 NFS4ERR_DQUOT when a user's quota is exceeded. 7621 ERRORS 7623 NFS4ERR_ACCES 7624 NFS4ERR_BADHANDLE 7625 NFS4ERR_BAD_STATEID 7626 NFS4ERR_DENIED 7627 NFS4ERR_DQUOT 7628 NFS4ERR_EXPIRED 7629 NFS4ERR_FBIG 7630 NFS4ERR_FHEXPIRED 7631 NFS4ERR_GRACE 7632 NFS4ERR_INVAL 7633 NFS4ERR_IO 7634 NFS4ERR_JUKEBOX 7635 NFS4ERR_LOCKED 7636 NFS4ERR_MOVED 7637 NFS4ERR_NOFILEHANDLE 7638 NFS4ERR_NOSPC 7640 Draft Specification NFS version 4 Protocol December 1999 7642 NFS4ERR_OLD_STATEID 7643 NFS4ERR_RESOURCE 7644 NFS4ERR_ROFS 7645 NFS4ERR_SERVERFAULT 7646 NFS4ERR_STALE 7647 NFS4ERR_STALE_STATEID 7648 NFS4ERR_WRONGSEC 7650 Draft Specification NFS version 4 Protocol December 1999 7652 15. NFS Version 4 Callback Procedures 7654 The procedures used for callbacks are defined in the following 7655 sections. In the interest of clarity, the terms "client" and 7656 "server" refer to NFS clients and servers, despite the fact that for 7657 an individual callback RPC, the sense of these terms would be 7658 precisely the opposite. 7660 15.1. Procedure 0: CB_NULL - No Operation 7662 SYNOPSIS 7664 7666 ARGUMENT 7668 void; 7670 RESULT 7672 void; 7674 DESCRIPTION 7676 Standard NULL procedure. Void argument, void response. This 7677 procedure has no functionality associated with it. 7679 ERRORS 7681 None. 7683 Draft Specification NFS version 4 Protocol December 1999 7685 15.2. Procedure 1: CB_COMPOUND - Compound Operations 7687 SYNOPSIS 7689 compoundargs -> compoundres 7691 ARGUMENT 7693 enum nfs_cb_opnum4 { 7694 OP_CB_GETATTR = 3, 7695 OP_CB_RECALL = 4 7696 }; 7698 union nfs_cb_argop4 switch (unsigned argop) { 7699 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 7700 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 7701 }; 7703 struct CB_COMPOUND4args { 7704 utf8string tag; 7705 uint32_t minorversion; 7706 nfs_cb_argop4 argarray<>; 7707 }; 7709 RESULT 7711 union nfs_cb_resop4 switch (unsigned resop){ 7712 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 7713 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 7714 }; 7716 struct CB_COMPOUND4args { 7717 utf8string tag; 7718 uint32_t minorversion; 7719 nfs_cb_argop4 argarray<>; 7720 }; 7722 struct CB_COMPOUND4res { 7723 nfsstat4 status; 7724 utf8string tag; 7725 nfs_cb_resop4 resarray<>; 7726 }; 7728 DESCRIPTION 7730 Draft Specification NFS version 4 Protocol December 1999 7732 The CB_COMPOUND procedure is used to combine one or more of the 7733 callback procedures into a single RPC request. The main callback 7734 RPC program has two main procedures: CB_NULL and CB_COMPOUND. All 7735 other operations use the CB_COMPOUND procedure as a wrapper. 7737 In the processing of the CB_COMPOUND procedure, the client may find 7738 that it does not have the available resources to execute any or all 7739 of the operations within the CB_COMPOUND sequence. In this case, 7740 the error NFS4ERR_RESOURCE will be returned for the particular 7741 operation within the CB_COMPOUND procedure where the resource 7742 exhaustion occurred. This assumes that all previous operations 7743 within the CB_COMPOUND sequence have been evaluated successfully. 7745 Contained within the CB_COMPOUND results is a 'status' field. This 7746 status must be equivalent to the status of the last operation that 7747 was executed within the CB_COMPOUND procedure. Therefore, if an 7748 operation incurred an error then the 'status' value will be the 7749 same error value as is being returned for the operation that 7750 failed. 7752 IMPLEMENTATION 7754 The CB_COMPOUND procedure is used to combine individual operations 7755 into a single RPC request. The client interprets each of the 7756 operations in turn. If an operation is executed by the client and 7757 the status of that operation is NFS4_OK, then the next operation in 7758 the CB_COMPOUND procedure is executed. The client continues this 7759 process until there are no more operations to be executed or one of 7760 the operations has a status value other than NFS4_OK. 7762 ERRORS 7764 All errors defined in the protocol 7766 Draft Specification NFS version 4 Protocol December 1999 7768 15.2.1. Operation 3: CB_GETATTR - Get Attributes 7770 SYNOPSIS 7772 fh, attrbits -> attrbits, attrvals 7774 ARGUMENT 7776 struct CB_GETATTR4args { 7777 nfs_fh4 fh; 7778 bitmap4 attr_request; 7779 }; 7781 RESULT 7783 struct CB_GETATTR4resok { 7784 fattr4 obj_attributes; 7785 }; 7787 union CB_GETATTR4res switch (nfsstat4 status) { 7788 case NFS4_OK: 7789 CB_GETATTR4resok resok4; 7790 default: 7791 void; 7792 }; 7794 DESCRIPTION 7796 The CB_GETATTR operation is used to obtain the attributes modified 7797 by an open delegate to allow the server to respond to GETATTR 7798 requests for a file which is the subject of an open delegation. 7800 IMPLEMENTATION 7802 The client returns attrbits and the associated attribute values 7803 only for attributes that it may change (change, time_modify, 7804 object_size). It may further limit the response to attributes that 7805 it has in fact changed during the scope of the delegation. 7807 ERRORS 7809 Draft Specification NFS version 4 Protocol December 1999 7811 NFS4ERR_FHEXPIRED 7812 NFS4ERR_RESOURCE 7814 Draft Specification NFS version 4 Protocol December 1999 7816 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation 7818 SYNOPSIS 7820 stateid, truncate, fh -> status 7822 ARGUMENT 7824 struct CB_RECALL4args { 7825 stateid4 stateid; 7826 bool truncate; 7827 nfs_fh4 fh; 7828 }; 7830 RESULT 7832 struct CB_RECALL4res { 7833 nfsstat4 status; 7834 }; 7836 DESCRIPTION 7838 The CB_RECALL operation is used to begin the process of recalling 7839 an open delegation and returning it to the server. 7841 The truncate flag is used to optimize recall for a file which is 7842 about to be truncated to zero. When it is set, the client is freed 7843 of obligation to propagate modified data for the file to the 7844 server, since this data is irrelevant. 7846 IMPLEMENTATION 7848 The client should reply to the callback immediately. Replying does 7849 not complete the recall. The recall is not complete until the 7850 delegation is returned using a DELEGRETURN. 7852 ERRORS 7854 NFS4ERR_FHEXPIRED 7855 NFS4ERR_RESOURCE 7857 Draft Specification NFS version 4 Protocol December 1999 7859 16. Security Considerations 7861 The major security feature to consider is the authentication of the 7862 user making the request of NFS service. Consideration should also be 7863 given to the integrity and privacy of this NFS request. These 7864 specific issues are discussed as part of the section on "RPC and 7865 Security Flavor". 7867 Draft Specification NFS version 4 Protocol December 1999 7869 17. RPC definition file 7871 /* 7872 * Copyright (C) The Internet Society (1998,1999). 7873 * All Rights Reserved. 7874 */ 7876 /* 7877 * nfs4_prot.x 7878 * 7879 */ 7881 %#pragma ident "@(#)nfs4_prot.x 1.70 99/12/16" 7883 /* 7884 * Basic typedefs for RFC 1832 data type definitions 7885 */ 7886 typedef int int32_t; 7887 typedef unsigned int uint32_t; 7888 typedef hyper int64_t; 7889 typedef unsigned hyper uint64_t; 7891 /* 7892 * Sizes 7893 */ 7894 const NFS4_FHSIZE = 128; 7895 const NFS4_CREATEVERFSIZE = 8; 7896 const NFS4_COOKIEVERFSIZE = 8; 7898 /* 7899 * File types 7900 */ 7901 enum nfs_ftype4 { 7902 NF4REG = 1, /* Regular File */ 7903 NF4DIR = 2, /* Directory */ 7904 NF4BLK = 3, /* Special File - block device */ 7905 NF4CHR = 4, /* Special File - character device */ 7906 NF4LNK = 5, /* Symbolic Link */ 7907 NF4SOCK = 6, /* Special File - socket */ 7908 NF4FIFO = 7, /* Special File - fifo */ 7909 NF4ATTRDIR = 8, /* Attribute Directory */ 7910 NF4NAMEDATTR = 9 /* Named Attribute */ 7911 }; 7913 /* 7914 * Error status 7915 */ 7916 enum nfsstat4 { 7918 Draft Specification NFS version 4 Protocol December 1999 7920 NFS4_OK = 0, 7921 NFS4ERR_PERM = 1, 7922 NFS4ERR_NOENT = 2, 7923 NFS4ERR_IO = 5, 7924 NFS4ERR_NXIO = 6, 7925 NFS4ERR_ACCES = 13, 7926 NFS4ERR_EXIST = 17, 7927 NFS4ERR_XDEV = 18, 7928 NFS4ERR_NODEV = 19, 7929 NFS4ERR_NOTDIR = 20, 7930 NFS4ERR_ISDIR = 21, 7931 NFS4ERR_INVAL = 22, 7932 NFS4ERR_FBIG = 27, 7933 NFS4ERR_NOSPC = 28, 7934 NFS4ERR_ROFS = 30, 7935 NFS4ERR_MLINK = 31, 7936 NFS4ERR_NAMETOOLONG = 63, 7937 NFS4ERR_NOTEMPTY = 66, 7938 NFS4ERR_DQUOT = 69, 7939 NFS4ERR_STALE = 70, 7940 NFS4ERR_BADHANDLE = 10001, 7941 NFS4ERR_NOT_SYNC = 10002, 7942 NFS4ERR_BAD_COOKIE = 10003, 7943 NFS4ERR_NOTSUPP = 10004, 7944 NFS4ERR_TOOSMALL = 10005, 7945 NFS4ERR_SERVERFAULT = 10006, 7946 NFS4ERR_BADTYPE = 10007, 7947 NFS4ERR_JUKEBOX = 10008, 7948 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 7949 NFS4ERR_DENIED = 10010,/* lock unavailable */ 7950 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 7951 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 7952 NFS4ERR_GRACE = 10013,/* in grace period */ 7953 NFS4ERR_FHEXPIRED = 10014,/* file handle expired */ 7954 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 7955 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 7956 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 7957 NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ 7958 NFS4ERR_MOVED = 10019,/* filesystem relocated */ 7959 NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */ 7960 NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */ 7961 NFS4ERR_STALE_CLIENTID = 10022, 7962 NFS4ERR_STALE_STATEID = 10023, 7963 NFS4ERR_OLD_STATEID = 10024, 7964 NFS4ERR_BAD_STATEID = 10025, 7965 NFS4ERR_BAD_SEQID = 10026, 7966 NFS4ERR_NOT_CONFIRMED = 10027 7967 }; 7969 Draft Specification NFS version 4 Protocol December 1999 7971 /* 7972 * Basic data types 7973 */ 7974 typedef uint32_t bitmap4<>; 7975 typedef uint64_t offset4; 7976 typedef uint32_t count4; 7977 typedef uint64_t length4; 7978 typedef uint64_t clientid4; 7979 typedef uint64_t stateid4; 7980 typedef uint32_t seqid4; 7981 typedef opaque utf8string<>; 7982 typedef utf8string component4; 7983 typedef component4 pathname4<>; 7984 typedef uint64_t nfs_lockid4; 7985 typedef uint64_t nfs_cookie4; 7986 typedef utf8string linktext4; 7987 typedef opaque sec_oid4<>; 7988 typedef uint32_t qop4; 7989 typedef uint32_t mode4; 7990 typedef uint32_t writeverf4; 7991 typedef opaque createverf4[NFS4_CREATEVERFSIZE]; 7992 typedef opaque cookieverf4[NFS4_COOKIEVERFSIZE]; 7994 /* 7995 * Timeval 7996 */ 7997 struct nfstime4 { 7998 int64_t seconds; 7999 uint32_t nseconds; 8000 }; 8002 /* 8003 * File access handle 8004 */ 8005 typedef opaque nfs_fh4; 8007 /* 8008 * File attribute definitions 8009 */ 8011 /* 8012 * FSID structure for major/minor 8013 */ 8014 struct fsid4 { 8015 uint64_t major; 8016 uint64_t minor; 8017 }; 8019 Draft Specification NFS version 4 Protocol December 1999 8021 /* 8022 * Filesystem locations attribute for relocation/migration 8023 */ 8024 struct fs_location4 { 8025 utf8string server<>; 8026 pathname4 rootpath; 8027 }; 8029 struct fs_locations4 { 8030 pathname4 fs_root; 8031 fs_location4 locations<>; 8032 }; 8034 /* 8035 * Various Access Control Entry definitions 8036 */ 8038 /* 8039 * Mask that indicates which Access Control Entries are supported. 8040 * Values for the fattr4_aclsupport attribute. 8041 */ 8042 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 8043 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 8044 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 8045 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 8047 typedef uint32_t acetype4; 8049 /* 8050 * acetype4 values, others can be added as needed. 8051 */ 8052 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 8053 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 8054 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 8055 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 8057 /* 8058 * ACE flag 8059 */ 8060 typedef uint32_t aceflag4; 8062 /* 8063 * ACE flag values 8064 */ 8065 const ACE4_FILE_INHERIT_ACE = 0x00000001; 8066 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 8068 Draft Specification NFS version 4 Protocol December 1999 8070 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 8071 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 8072 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 8073 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 8074 const ACE4_IDENTIFIER_GROUP = 0x00000040; 8076 /* 8077 * ACE mask 8078 */ 8079 typedef uint32_t acemask4; 8081 /* 8082 * ACE mask values 8083 */ 8084 const ACE4_READ_DATA = 0x00000001; 8085 const ACE4_LIST_DIRECTORY = 0x00000001; 8086 const ACE4_WRITE_DATA = 0x00000002; 8087 const ACE4_ADD_FILE = 0x00000002; 8088 const ACE4_APPEND_DATA = 0x00000004; 8089 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 8090 const ACE4_READ_STREAMS = 0x00000008; 8091 const ACE4_WRITE_STREAMS = 0x00000010; 8092 const ACE4_EXECUTE = 0x00000020; 8093 const ACE4_DELETE_CHILD = 0x00000040; 8094 const ACE4_READ_ATTRIBUTES = 0x00000080; 8095 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 8097 const ACE4_DELETE = 0x00010000; 8098 const ACE4_READ_ACL = 0x00020000; 8099 const ACE4_WRITE_ACL = 0x00040000; 8100 const ACE4_WRITE_OWNER = 0x00080000; 8101 const ACE4_SYNCHRONIZE = 0x00100000; 8103 /* 8104 * ACE4_GENERIC_READ -- defined as combination of 8105 * ACE4_READ_ACL | 8106 * ACE4_READ_DATA | 8107 * ACE4_READ_ATTRIBUTES | 8108 * ACE4_SYNCHRONIZE 8109 */ 8111 const ACE4_GENERIC_READ = 0x00120081; 8113 /* 8114 * ACE4_GENERIC_WRITE -- defined as combination of 8115 * ACE4_READ_ACL | 8116 * ACE4_WRITE_DATA | 8118 Draft Specification NFS version 4 Protocol December 1999 8120 * ACE4_WRITE_ATTRIBUTES | 8121 * ACE4_WRITE_ACL | 8122 * ACE4_APPEND_DATA | 8123 * ACE4_SYNCHRONIZE 8124 */ 8125 const ACE4_GENERIC_WRITE = 0x00160102; 8127 /* 8128 * ACE4_GENERIC_EXECUTE -- defined as combination of 8129 * ACE4_READ_ACL 8130 * ACE4_READ_ATTRIBUTES 8131 * ACE4_EXECUTE 8132 * ACE4_SYNCHRONIZE 8133 */ 8134 const ACE4_GENERIC_EXECUTE = 0x001200A0; 8136 /* 8137 * Access Control Entry definition 8138 */ 8139 struct nfsace4 { 8140 acetype4 type; 8141 aceflag4 flag; 8142 acemask4 access_mask; 8143 utf8string who; 8144 }; 8146 /* 8147 * Special data/attribute associated with 8148 * file types NF4BLK and NF4CHR. 8149 */ 8150 struct specdata4 { 8151 uint32_t specdata1; 8152 uint32_t specdata2; 8153 }; 8155 /* 8156 * Values for fattr4_fh_expire_type 8157 */ 8158 const FH4_PERSISTENT = 0x00000000; 8159 const FH4_NOEXPIRE_WITH_OPEN = 0x00000001; 8160 const FH4_VOLATILE_ANY = 0x00000002; 8161 const FH4_VOL_MIGRATION = 0x00000004; 8162 const FH4_VOL_RENAME = 0x00000008; 8164 typedef bitmap4 fattr4_supported_attrs; 8166 Draft Specification NFS version 4 Protocol December 1999 8168 typedef nfs_ftype4 fattr4_type; 8169 typedef uint32_t fattr4_fh_expire_type; 8170 typedef uint64_t fattr4_change; 8171 typedef uint64_t fattr4_size; 8172 typedef bool fattr4_link_support; 8173 typedef bool fattr4_symlink_support; 8174 typedef bool fattr4_named_attr; 8175 typedef fsid4 fattr4_fsid; 8176 typedef bool fattr4_unique_handles; 8177 typedef uint32_t fattr4_lease_time; 8178 typedef nfsstat4 fattr4_rdattr_error; 8180 typedef nfsace4 fattr4_acl<>; 8181 typedef uint32_t fattr4_aclsupport; 8182 typedef bool fattr4_archive; 8183 typedef bool fattr4_cansettime; 8184 typedef bool fattr4_case_insensitive; 8185 typedef bool fattr4_case_preserving; 8186 typedef bool fattr4_chown_restricted; 8187 typedef uint64_t fattr4_fileid; 8188 typedef uint64_t fattr4_files_avail; 8189 typedef nfs_fh4 fattr4_filehandle; 8190 typedef uint64_t fattr4_files_free; 8191 typedef uint64_t fattr4_files_total; 8192 typedef fs_locations4 fattr4_fs_locations; 8193 typedef bool fattr4_hidden; 8194 typedef bool fattr4_homogeneous; 8195 typedef uint64_t fattr4_maxfilesize; 8196 typedef uint32_t fattr4_maxlink; 8197 typedef uint32_t fattr4_maxname; 8198 typedef uint64_t fattr4_maxread; 8199 typedef uint64_t fattr4_maxwrite; 8200 typedef utf8string fattr4_mimetype; 8201 typedef mode4 fattr4_mode; 8202 typedef bool fattr4_no_trunc; 8203 typedef uint32_t fattr4_numlinks; 8204 typedef utf8string fattr4_owner; 8205 typedef utf8string fattr4_owner_group; 8206 typedef uint64_t fattr4_quota_hard; 8207 typedef uint64_t fattr4_quota_soft; 8208 typedef uint64_t fattr4_quota_used; 8209 typedef specdata4 fattr4_rawdev; 8210 typedef uint64_t fattr4_space_avail; 8211 typedef uint64_t fattr4_space_free; 8212 typedef uint64_t fattr4_space_total; 8213 typedef uint64_t fattr4_space_used; 8214 typedef bool fattr4_system; 8215 typedef nfstime4 fattr4_time_access; 8217 Draft Specification NFS version 4 Protocol December 1999 8219 typedef nfstime4 fattr4_time_backup; 8220 typedef nfstime4 fattr4_time_create; 8221 typedef nfstime4 fattr4_time_delta; 8222 typedef nfstime4 fattr4_time_metadata; 8223 typedef nfstime4 fattr4_time_modify; 8224 typedef utf8string fattr4_version; 8225 typedef nfstime4 fattr4_volatility; 8227 /* 8228 * Mandatory Attributes 8229 */ 8230 const FATTR4_SUPPORTED_ATTRS = 0; 8231 const FATTR4_TYPE = 1; 8232 const FATTR4_PERSISTENT_FH = 2; 8233 const FATTR4_CHANGE = 3; 8234 const FATTR4_SIZE = 4; 8235 const FATTR4_LINK_SUPPORT = 5; 8236 const FATTR4_SYMLINK_SUPPORT = 6; 8237 const FATTR4_NAMED_ATTR = 7; 8238 const FATTR4_FSID = 8; 8239 const FATTR4_UNIQUE_HANDLES = 9; 8240 const FATTR4_LEASE_TIME = 10; 8241 const FATTR4_RDATTR_ERROR = 11; 8243 /* 8244 * Recommended Attributes 8245 */ 8246 const FATTR4_ACL = 12; 8247 const FATTR4_ARCHIVE = 13; 8248 const FATTR4_CANSETTIME = 14; 8249 const FATTR4_CASE_INSENSITIVE = 15; 8250 const FATTR4_CASE_PRESERVING = 16; 8251 const FATTR4_CHOWN_RESTRICTED = 17; 8252 const FATTR4_FILEHANDLE = 18; 8253 const FATTR4_FILEID = 19; 8254 const FATTR4_FILES_AVAIL = 20; 8255 const FATTR4_FILES_FREE = 21; 8256 const FATTR4_FILES_TOTAL = 22; 8257 const FATTR4_FS_LOCATIONS = 23; 8258 const FATTR4_HIDDEN = 24; 8259 const FATTR4_HOMOGENEOUS = 25; 8260 const FATTR4_MAXFILESIZE = 26; 8261 const FATTR4_MAXLINK = 27; 8262 const FATTR4_MAXNAME = 28; 8263 const FATTR4_MAXREAD = 29; 8264 const FATTR4_MAXWRITE = 30; 8265 const FATTR4_MIMETYPE = 31; 8267 Draft Specification NFS version 4 Protocol December 1999 8269 const FATTR4_MODE = 32; 8270 const FATTR4_NO_TRUNC = 33; 8271 const FATTR4_NUMLINKS = 34; 8272 const FATTR4_OWNER = 35; 8273 const FATTR4_OWNER_GROUP = 36; 8274 const FATTR4_QUOTA_HARD = 37; 8275 const FATTR4_QUOTA_SOFT = 38; 8276 const FATTR4_QUOTA_USED = 39; 8277 const FATTR4_RAWDEV = 40; 8278 const FATTR4_SPACE_AVAIL = 41; 8279 const FATTR4_SPACE_FREE = 42; 8280 const FATTR4_SPACE_TOTAL = 43; 8281 const FATTR4_SPACE_USED = 44; 8282 const FATTR4_SYSTEM = 45; 8283 const FATTR4_TIME_ACCESS = 46; 8284 const FATTR4_TIME_BACKUP = 47; 8285 const FATTR4_TIME_CREATE = 48; 8286 const FATTR4_TIME_DELTA = 49; 8287 const FATTR4_TIME_METADATA = 50; 8288 const FATTR4_TIME_MODIFY = 51; 8289 const FATTR4_VERSION = 52; 8290 const FATTR4_VOLATILITY = 53; 8292 typedef opaque attrlist4<>; 8294 /* 8295 * File attribute container 8296 */ 8297 struct fattr4 { 8298 bitmap4 attrmask; 8299 attrlist4 attr_vals; 8300 }; 8302 /* 8303 * Change info for the client 8304 */ 8305 struct change_info4 { 8306 bool atomic; 8307 fattr4_change before; 8308 fattr4_change after; 8309 }; 8311 struct clientaddr4 { 8312 /* see struct rpcb in RFC 1833 */ 8313 string r_netid<>; /* network id */ 8314 string r_addr<>; /* universal address */ 8315 }; 8317 Draft Specification NFS version 4 Protocol December 1999 8319 /* 8320 * Callback program info as provided by the client 8321 */ 8322 struct cb_client4 { 8323 unsigned int cb_program; 8324 clientaddr4 cb_location; 8325 }; 8327 /* 8328 * Client ID 8329 */ 8330 struct nfs_client_id4 { 8331 opaque verifier[4]; 8332 opaque id<>; 8333 }; 8335 struct nfs_lockowner4 { 8336 clientid4 clientid; 8337 opaque owner<>; 8338 }; 8340 enum nfs_lock_type4 { 8341 READ_LT = 1, 8342 WRITE_LT = 2, 8343 READW_LT = 3, /* blocking read */ 8344 WRITEW_LT = 4 /* blocking write */ 8345 }; 8347 /* 8348 * ACCESS: Check access permission 8349 */ 8350 const ACCESS4_READ = 0x00000001; 8351 const ACCESS4_LOOKUP = 0x00000002; 8352 const ACCESS4_MODIFY = 0x00000004; 8353 const ACCESS4_EXTEND = 0x00000008; 8354 const ACCESS4_DELETE = 0x00000010; 8355 const ACCESS4_EXECUTE = 0x00000020; 8357 struct ACCESS4args { 8358 /* CURRENT_FH: object */ 8359 uint32_t access; 8360 }; 8362 struct ACCESS4resok { 8363 uint32_t supported; 8364 uint32_t access; 8365 }; 8367 Draft Specification NFS version 4 Protocol December 1999 8369 union ACCESS4res switch (nfsstat4 status) { 8370 case NFS4_OK: 8371 ACCESS4resok resok4; 8372 default: 8373 void; 8374 }; 8376 /* 8377 * CLOSE: Close a file and release share locks 8378 */ 8379 struct CLOSE4args { 8380 /* CURRENT_FH: object */ 8381 stateid4 stateid; 8382 }; 8384 union CLOSE4res switch (nfsstat4 status) { 8385 case NFS4_OK: 8386 stateid4 stateid; 8387 default: 8388 void; 8389 }; 8391 /* 8392 * COMMIT: Commit cached data on server to stable storage 8393 */ 8394 struct COMMIT4args { 8395 /* CURRENT_FH: file */ 8396 offset4 offset; 8397 count4 count; 8398 }; 8400 struct COMMIT4resok { 8401 writeverf4 verf; 8402 }; 8404 union COMMIT4res switch (nfsstat4 status) { 8405 case NFS4_OK: 8406 COMMIT4resok resok4; 8407 default: 8408 void; 8409 }; 8411 /* 8412 * CREATE: Create a file 8413 */ 8414 union createtype4 switch (nfs_ftype4 type) { 8415 case NF4LNK: 8417 Draft Specification NFS version 4 Protocol December 1999 8419 linktext4 linkdata; 8420 case NF4BLK: 8421 case NF4CHR: 8422 specdata4 devdata; 8423 case NF4SOCK: 8424 case NF4FIFO: 8425 case NF4DIR: 8426 case NF4ATTRDIR: 8427 void; 8428 }; 8430 struct CREATE4args { 8431 /* CURRENT_FH: directory for creation */ 8432 component4 objname; 8433 createtype4 objtype; 8434 }; 8436 struct CREATE4resok { 8437 change_info4 cinfo; 8438 }; 8440 union CREATE4res switch (nfsstat4 status) { 8441 case NFS4_OK: 8442 CREATE4resok resok4; 8443 default: 8444 void; 8445 }; 8447 /* 8448 * DELEGPURGE: Purge Delegations Awaiting Recovery 8449 */ 8450 struct DELEGPURGE4args { 8451 clientid4 clientid; 8452 }; 8454 struct DELEGPURGE4res { 8455 nfsstat4 status; 8456 }; 8458 /* 8459 * DELEGRETURN: Return a delegation 8460 */ 8461 struct DELEGRETURN4args { 8462 stateid4 stateid; 8463 }; 8465 struct DELEGRETURN4res { 8466 nfsstat4 status; 8468 Draft Specification NFS version 4 Protocol December 1999 8470 }; 8472 /* 8473 * GETATTR: Get file attributes 8474 */ 8475 struct GETATTR4args { 8476 /* CURRENT_FH: directory or file */ 8477 bitmap4 attr_request; 8478 }; 8480 struct GETATTR4resok { 8481 fattr4 obj_attributes; 8482 }; 8484 union GETATTR4res switch (nfsstat4 status) { 8485 case NFS4_OK: 8486 GETATTR4resok resok4; 8487 default: 8488 void; 8489 }; 8491 /* 8492 * GETFH: Get current filehandle 8493 */ 8494 struct GETFH4resok { 8495 nfs_fh4 object; 8496 }; 8498 union GETFH4res switch (nfsstat4 status) { 8499 case NFS4_OK: 8500 GETFH4resok resok4; 8501 default: 8502 void; 8503 }; 8505 /* 8506 * LINK: Create link to an object 8507 */ 8508 struct LINK4args { 8509 /* SAVED_FH: source object */ 8510 /* CURRENT_FH: target directory */ 8511 component4 newname; 8512 }; 8514 struct LINK4resok { 8515 change_info4 cinfo; 8516 }; 8518 Draft Specification NFS version 4 Protocol December 1999 8520 union LINK4res switch (nfsstat4 status) { 8521 case NFS4_OK: 8522 LINK4resok resok4; 8523 default: 8524 void; 8525 }; 8527 /* 8528 * LOCK/LOCKT/LOCKU: Record lock management 8529 */ 8530 struct LOCK4args { 8531 /* CURRENT_FH: file */ 8532 nfs_lock_type4 locktype; 8533 seqid4 seqid; 8534 bool reclaim; 8535 stateid4 stateid; 8536 offset4 offset; 8537 length4 length; 8538 }; 8540 union LOCK4res switch (nfsstat4 status) { 8541 case NFS4_OK: 8542 stateid4 stateid; 8543 default: 8544 void; 8545 }; 8547 struct LOCKT4args { 8548 /* CURRENT_FH: file */ 8549 nfs_lock_type4 locktype; 8550 nfs_lockowner4 owner; 8551 offset4 offset; 8552 length4 length; 8553 }; 8555 union LOCKT4res switch (nfsstat4 status) { 8556 case NFS4ERR_DENIED: 8557 nfs_lockowner4 owner; 8558 case NFS4_OK: 8559 void; 8560 default: 8561 void; 8562 }; 8564 struct LOCKU4args { 8565 /* CURRENT_FH: file */ 8566 nfs_lock_type4 type; 8567 seqid4 seqid; 8569 Draft Specification NFS version 4 Protocol December 1999 8571 stateid4 stateid; 8572 offset4 offset; 8573 length4 length; 8574 }; 8576 union LOCKU4res switch (nfsstat4 status) { 8577 case NFS4_OK: 8578 stateid4 stateid; 8579 default: 8580 void; 8581 }; 8583 /* 8584 * LOOKUP: Lookup filename 8585 */ 8586 struct LOOKUP4args { 8587 /* CURRENT_FH: directory */ 8588 pathname4 path; 8589 }; 8591 struct LOOKUP4res { 8592 /* CURRENT_FH: object */ 8593 nfsstat4 status; 8594 }; 8596 /* 8597 * LOOKUPP: Lookup parent directory 8598 */ 8599 struct LOOKUPP4res { 8600 /* CURRENT_FH: directory */ 8601 nfsstat4 status; 8602 }; 8604 /* 8605 * NVERIFY: Verify attributes different 8606 */ 8607 struct NVERIFY4args { 8608 /* CURRENT_FH: object */ 8609 bitmap4 attr_request; 8610 fattr4 obj_attributes; 8611 }; 8613 struct NVERIFY4res { 8614 nfsstat4 status; 8615 }; 8617 /* 8618 * Various definitions for OPEN 8620 Draft Specification NFS version 4 Protocol December 1999 8622 */ 8623 enum createmode4 { 8624 UNCHECKED4 = 0, 8625 GUARDED4 = 1, 8626 EXCLUSIVE4 = 2 8627 }; 8629 union createhow4 switch (createmode4 mode) { 8630 case UNCHECKED4: 8631 case GUARDED4: 8632 fattr4 createattrs; 8633 case EXCLUSIVE4: 8634 createverf4 verf; 8635 }; 8637 enum opentype4 { 8638 OPEN4_NOCREATE = 0, 8639 OPEN4_CREATE = 1 8640 }; 8642 union openflag4 switch (opentype4 opentype) { 8643 case OPEN4_CREATE: 8644 createhow4 how; 8645 default: 8646 void; 8647 }; 8649 /* Next definitions used for OPEN delegation */ 8650 enum limit_by4 { 8651 NFS_LIMIT_SIZE = 1, 8652 NFS_LIMIT_BLOCKS = 2 8653 /* others as needed */ 8654 }; 8656 struct nfs_modified_limit4 { 8657 uint32_t num_blocks; 8658 uint32_t bytes_per_block; 8659 }; 8661 union nfs_space_limit4 switch (limit_by4 limitby) { 8662 /* limit specified as file size */ 8663 case NFS_LIMIT_SIZE: 8664 uint64_t filesize; 8665 /* limit specified by number of blocks */ 8666 case NFS_LIMIT_BLOCKS: 8667 nfs_modified_limit4 mod_blocks; 8668 } ; 8670 Draft Specification NFS version 4 Protocol December 1999 8672 /* 8673 * Share Access and Deny constants for open argument 8674 */ 8675 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 8676 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 8677 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 8679 const OPEN4_SHARE_DENY_NONE = 0x00000000; 8680 const OPEN4_SHARE_DENY_READ = 0x00000001; 8681 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 8682 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 8684 enum open_delegation_type4 { 8685 OPEN_DELEGATE_NONE = 0, 8686 OPEN_DELEGATE_READ = 1, 8687 OPEN_DELEGATE_WRITE = 2 8688 }; 8690 enum open_claim_type4 { 8691 CLAIM_NULL = 0, 8692 CLAIM_PREVIOUS = 1, 8693 CLAIM_DELEGATE_CUR = 2, 8694 CLAIM_DELEGATE_PREV = 3 8695 }; 8697 struct open_claim_delegate_cur4 { 8698 pathname4 file; 8699 stateid4 delegate_stateid; 8700 }; 8702 union open_claim4 switch (open_claim_type4 claim) { 8703 /* 8704 * No special rights to file. Ordinary OPEN of the specified file. 8705 */ 8706 case CLAIM_NULL: 8707 /* CURRENT_FH: directory */ 8708 pathname4 file; 8710 /* 8711 * Right to the file established by an open previous to server 8712 * reboot. File identified by filehandle obtained at that time 8713 * rather than by name. 8714 */ 8715 case CLAIM_PREVIOUS: 8716 /* CURRENT_FH: file being reclaimed */ 8717 uint32_t delegate_type; 8719 /* 8721 Draft Specification NFS version 4 Protocol December 1999 8723 * Right to file based on a delegation granted by the server. 8724 * File is specified by name. 8725 */ 8726 case CLAIM_DELEGATE_CUR: 8727 /* CURRENT_FH: directory */ 8728 open_claim_delegate_cur4 delegate_cur_info; 8730 /* Right to file based on a delegation granted to a previous boot 8731 * instance of the client. File is specified by name. 8732 */ 8733 case CLAIM_DELEGATE_PREV: 8734 /* CURRENT_FH: directory */ 8735 pathname4 file_delegate_prev; 8736 }; 8738 /* 8739 * OPEN: Open a file, potentially receiving an open delegation 8740 */ 8741 struct OPEN4args { 8742 open_claim4 claim; 8743 openflag4 openhow; 8744 nfs_lockowner4 owner; 8745 seqid4 seqid; 8746 uint32_t share_access; 8747 uint32_t share_deny; 8748 }; 8750 /* 8751 * Result flags 8752 */ 8753 /* Mandatory locking is in effect for this file. */ 8754 const OPEN4_RESULT_MLOCK = 0x00000001; 8756 struct open_read_delegation4 { 8757 stateid4 stateid; /* Stateid for delegation*/ 8758 bool recall; /* Pre-recalled flag for 8759 delegations obtained 8760 by reclaim 8761 (CLAIM_PREVIOUS) */ 8762 nfsace4 permissions; /* Defines users who don't 8763 need an ACCESS call to 8764 open for read */ 8765 }; 8767 struct open_write_delegation4 { 8768 stateid4 stateid; /* Stateid for delegation 8769 be flushed to the server 8770 on close. */ 8772 Draft Specification NFS version 4 Protocol December 1999 8774 bool recall; /* Pre-recalled flag for 8775 delegations obtained 8776 by reclaim 8777 (CLAIM_PREVIOUS) */ 8778 nfs_space_limit4 space_limit; /* Defines condition that 8779 the client must check to 8780 determine whether the 8781 file needs to be flushed 8782 to the server on close. 8783 */ 8784 nfsace4 permissions; /* Defines users who don't 8785 need an ACCESS call as 8786 part of a delegated 8787 open. */ 8788 }; 8790 union open_delegation4 8791 switch (open_delegation_type4 delegation_type) { 8792 case OPEN_DELEGATE_NONE: 8793 void; 8794 case OPEN_DELEGATE_READ: 8795 open_read_delegation4 read; 8796 case OPEN_DELEGATE_WRITE: 8797 open_write_delegation4 write; 8798 }; 8800 struct OPEN4resok { 8801 stateid4 stateid; /* Stateid for open */ 8802 uint32_t rflags; /* Result flags */ 8803 cookieverf4 open_confirm; /* OPEN_CONFIRM verifier */ 8804 open_delegation4 delegation; /* Info on any open 8805 delegation */ 8806 }; 8808 union OPEN4res switch (nfsstat4 status) { 8809 case NFS4_OK: 8810 /* CURRENT_FH: opened file */ 8811 OPEN4resok result; 8812 default: 8813 void; 8814 }; 8816 /* 8817 * OPENATTR: open named attributes directory 8818 */ 8819 struct OPENATTR4res { 8820 /* CURRENT_FH: name attr directory*/ 8821 nfsstat4 status; 8823 Draft Specification NFS version 4 Protocol December 1999 8825 }; 8827 struct OPEN_CONFIRM4args { 8828 /* CURRENT_FH: opened file */ 8829 seqid4 seqid; 8830 cookieverf4 open_confirm; /* OPEN_CONFIRM verifier */ 8831 }; 8833 struct OPEN_CONFIRM4resok { 8834 stateid4 stateid; 8835 }; 8837 union OPEN_CONFIRM4res switch (nfsstat4 status) { 8838 case NFS4_OK: 8839 OPEN_CONFIRM4resok resok4; 8840 default: 8841 void; 8842 }; 8844 /* 8845 * PUTFH: Set current filehandle 8846 */ 8847 struct PUTFH4args { 8848 nfs_fh4 object; 8849 }; 8851 struct PUTFH4res { 8852 /* CURRENT_FH: */ 8853 nfsstat4 status; 8854 }; 8856 /* 8857 * PUTPUBFH: Set public filehandle 8858 */ 8859 struct PUTPUBFH4res { 8860 /* CURRENT_FH: public fh */ 8861 nfsstat4 status; 8862 }; 8864 /* 8865 * PUTROOTFH: Set root filehandle 8866 */ 8867 struct PUTROOTFH4res { 8868 /* CURRENT_FH: root fh */ 8869 nfsstat4 status; 8870 }; 8872 /* 8874 Draft Specification NFS version 4 Protocol December 1999 8876 * READ: Read from file 8877 */ 8878 struct READ4args { 8879 /* CURRENT_FH: file */ 8880 stateid4 stateid; 8881 offset4 offset; 8882 count4 count; 8883 }; 8885 struct READ4resok { 8886 bool eof; 8887 opaque data<>; 8888 }; 8890 union READ4res switch (nfsstat4 status) { 8891 case NFS4_OK: 8892 READ4resok resok4; 8893 default: 8894 void; 8895 }; 8897 /* 8898 * READDIR: Read directory 8899 */ 8900 struct READDIR4args { 8901 /* CURRENT_FH: directory */ 8902 nfs_cookie4 cookie; 8903 cookieverf4 cookieverf; 8904 count4 dircount; 8905 count4 maxcount; 8906 bitmap4 attr_request; 8907 }; 8909 struct entry4 { 8910 nfs_cookie4 cookie; 8911 component4 name; 8912 fattr4 attrs; 8913 entry4 *nextentry; 8914 }; 8916 struct dirlist4 { 8917 entry4 *entries; 8918 bool eof; 8919 }; 8921 struct READDIR4resok { 8922 cookieverf4 cookieverf; 8923 dirlist4 reply; 8925 Draft Specification NFS version 4 Protocol December 1999 8927 }; 8929 union READDIR4res switch (nfsstat4 status) { 8930 case NFS4_OK: 8931 READDIR4resok resok4; 8932 default: 8933 void; 8934 }; 8936 /* 8937 * READLINK: Read symbolic link 8938 */ 8939 struct READLINK4resok { 8940 linktext4 link; 8941 }; 8943 union READLINK4res switch (nfsstat4 status) { 8944 case NFS4_OK: 8945 READLINK4resok resok4; 8946 default: 8947 void; 8948 }; 8950 /* 8951 * REMOVE: Remove filesystem object 8952 */ 8953 struct REMOVE4args { 8954 /* CURRENT_FH: directory */ 8955 component4 target; 8956 }; 8958 struct REMOVE4resok { 8959 change_info4 cinfo; 8960 }; 8962 union REMOVE4res switch (nfsstat4 status) { 8963 case NFS4_OK: 8964 REMOVE4resok resok4; 8965 default: 8966 void; 8967 }; 8969 /* 8970 * RENAME: Rename directory entry 8971 */ 8972 struct RENAME4args { 8974 Draft Specification NFS version 4 Protocol December 1999 8976 /* SAVED_FH: source directory */ 8977 component4 oldname; 8978 /* CURRENT_FH: target directory */ 8979 component4 newname; 8980 }; 8982 struct RENAME4resok { 8983 change_info4 source_cinfo; 8984 change_info4 target_cinfo; 8985 }; 8987 union RENAME4res switch (nfsstat4 status) { 8988 case NFS4_OK: 8989 RENAME4resok resok4; 8990 default: 8991 void; 8992 }; 8994 /* 8995 * RENEW: Renew a Lease 8996 */ 8997 struct RENEW4args { 8998 stateid4 stateid; 8999 }; 9001 struct RENEW4res { 9002 nfsstat4 status; 9003 }; 9005 /* 9006 * RESTOREFH: Restore saved filehandle 9007 */ 9009 struct RESTOREFH4res { 9010 /* CURRENT_FH: value of saved fh */ 9011 nfsstat4 status; 9012 }; 9014 /* 9015 * SAVEFH: Save current filehandle 9016 */ 9017 struct SAVEFH4res { 9018 /* SAVED_FH: value of current fh */ 9019 nfsstat4 status; 9020 }; 9022 /* 9023 * SECINFO: Obtain Available Security Mechanisms 9025 Draft Specification NFS version 4 Protocol December 1999 9027 */ 9028 struct SECINFO4args { 9029 /* CURRENT_FH: */ 9030 component4 name; 9031 }; 9033 /* 9034 * From RFC 2203 9035 */ 9036 enum rpc_gss_svc_t { 9037 RPC_GSS_SVC_NONE = 1, 9038 RPC_GSS_SVC_INTEGRITY = 2, 9039 RPC_GSS_SVC_PRIVACY = 3 9040 }; 9042 struct rpcsec_gss_info { 9043 sec_oid4 oid; 9044 qop4 qop; 9045 rpc_gss_svc_t service; 9046 }; 9048 struct secinfo4 { 9049 uint32_t flavor; 9050 /* null for AUTH_SYS, AUTH_NONE; 9051 contains rpcsec_gss_info for 9052 RPCSEC_GSS. */ 9053 opaque flavor_info<>; 9054 }; 9056 typedef secinfo4 SECINFO4resok<>; 9058 union SECINFO4res switch (nfsstat4 status) { 9059 case NFS4_OK: 9060 SECINFO4resok resok4; 9061 default: 9062 void; 9063 }; 9065 /* 9066 * SETATTR: Set attributes 9067 */ 9068 struct SETATTR4args { 9069 /* CURRENT_FH: target object */ 9070 stateid4 stateid; 9071 fattr4 obj_attributes; 9072 }; 9074 struct SETATTR4res { 9076 Draft Specification NFS version 4 Protocol December 1999 9078 nfsstat4 status; 9079 bitmap4 attrsset; 9080 }; 9082 /* 9083 * SETCLIENTID 9084 */ 9085 struct SETCLIENTID4args { 9086 seqid4 seqid; 9087 bool confirm; 9088 nfs_client_id4 client; 9089 cb_client4 callback; 9090 }; 9092 struct SETCLIENTID4resok { 9093 clientid4 clientid; 9094 cookieverf4 setclientid_confirm; 9095 }; 9097 union SETCLIENTID4res switch (nfsstat4 status) { 9098 case NFS4_OK: 9099 SETCLIENTID4resok resok4; 9100 case NFS4ERR_CLID_INUSE: 9101 clientaddr4 client_using; 9102 default: 9103 void; 9104 }; 9106 struct SETCLIENTID_CONFIRM4args { 9107 seqid4 seqid; 9108 cookieverf4 setclientid_confirm; 9109 }; 9111 struct SETCLIENTID_CONFIRM4res { 9112 nfsstat4 status; 9113 }; 9115 /* 9116 * VERIFY: Verify attributes same 9117 */ 9118 struct VERIFY4args { 9119 /* CURRENT_FH: object */ 9120 bitmap4 attr_request; 9121 fattr4 obj_attributes; 9122 }; 9124 struct VERIFY4res { 9125 nfsstat4 status; 9127 Draft Specification NFS version 4 Protocol December 1999 9129 }; 9131 /* 9132 * WRITE: Write to file 9133 */ 9134 enum stable_how4 { 9135 UNSTABLE4 = 0, 9136 DATA_SYNC4 = 1, 9137 FILE_SYNC4 = 2 9138 }; 9140 struct WRITE4args { 9141 /* CURRENT_FH: file */ 9142 stateid4 stateid; 9143 offset4 offset; 9144 stable_how4 stable; 9145 opaque data<>; 9146 }; 9148 struct WRITE4resok { 9149 count4 count; 9150 stable_how4 committed; 9151 writeverf4 verf; 9152 }; 9154 union WRITE4res switch (nfsstat4 status) { 9155 case NFS4_OK: 9156 WRITE4resok resok4; 9157 default: 9158 void; 9159 }; 9161 /* 9162 * Operation arrays 9163 */ 9165 enum nfs_opnum4 { 9166 OP_ACCESS = 3, 9167 OP_CLOSE = 4, 9168 OP_COMMIT = 5, 9169 OP_CREATE = 6, 9170 OP_DELEGPURGE = 7, 9171 OP_DELEGRETURN = 8, 9172 OP_GETATTR = 9, 9173 OP_GETFH = 10, 9174 OP_LINK = 11, 9175 OP_LOCK = 12, 9176 OP_LOCKT = 13, 9178 Draft Specification NFS version 4 Protocol December 1999 9180 OP_LOCKU = 14, 9181 OP_LOOKUP = 15, 9182 OP_LOOKUPP = 16, 9183 OP_NVERIFY = 17, 9184 OP_OPEN = 18, 9185 OP_OPENATTR = 19, 9186 OP_OPEN_CONFIRM = 20, 9187 OP_PUTFH = 21, 9188 OP_PUTPUBFH = 22, 9189 OP_PUTROOTFH = 23, 9190 OP_READ = 24, 9191 OP_READDIR = 25, 9192 OP_READLINK = 26, 9193 OP_REMOVE = 27, 9194 OP_RENAME = 28, 9195 OP_RENEW = 29, 9196 OP_RESTOREFH = 30, 9197 OP_SAVEFH = 31, 9198 OP_SECINFO = 32, 9199 OP_SETATTR = 33, 9200 OP_SETCLIENTID = 34, 9201 OP_SETCLIENTID_CONFIRM = 35, 9202 OP_VERIFY = 36, 9203 OP_WRITE = 37 9204 }; 9206 union nfs_argop4 switch (nfs_opnum4 argop) { 9207 case OP_ACCESS: ACCESS4args opaccess; 9208 case OP_CLOSE: CLOSE4args opclose; 9209 case OP_COMMIT: COMMIT4args opcommit; 9210 case OP_CREATE: CREATE4args opcreate; 9211 case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; 9212 case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; 9213 case OP_GETATTR: GETATTR4args opgetattr; 9214 case OP_GETFH: void; 9215 case OP_LINK: LINK4args oplink; 9216 case OP_LOCK: LOCK4args oplock; 9217 case OP_LOCKT: LOCK4args oplockt; 9218 case OP_LOCKU: LOCK4args oplocku; 9219 case OP_LOOKUP: LOOKUP4args oplookup; 9220 case OP_LOOKUPP: void; 9221 case OP_NVERIFY: NVERIFY4args opnverify; 9222 case OP_OPEN: OPEN4args opopen; 9223 case OP_OPENATTR: void; 9224 case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; 9225 case OP_PUTFH: PUTFH4args opputfh; 9226 case OP_PUTPUBFH: void; 9227 case OP_PUTROOTFH: void; 9229 Draft Specification NFS version 4 Protocol December 1999 9231 case OP_READ: READ4args opread; 9232 case OP_READDIR: READDIR4args opreaddir; 9233 case OP_READLINK: void; 9234 case OP_REMOVE: REMOVE4args opremove; 9235 case OP_RENAME: RENAME4args oprename; 9236 case OP_RENEW: RENEW4args oprenew; 9237 case OP_RESTOREFH: void; 9238 case OP_SAVEFH: void; 9239 case OP_SECINFO: SECINFO4args opsecinfo; 9240 case OP_SETATTR: SETATTR4args opsetattr; 9241 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 9242 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args 9243 opsetclientid_confirm; 9244 case OP_VERIFY: VERIFY4args opverify; 9245 case OP_WRITE: WRITE4args opwrite; 9246 }; 9248 union nfs_resop4 switch (nfs_opnum4 resop){ 9249 case OP_ACCESS: ACCESS4res opaccess; 9250 case OP_CLOSE: CLOSE4res opclose; 9251 case OP_COMMIT: COMMIT4res opcommit; 9252 case OP_CREATE: CREATE4res opcreate; 9253 case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; 9254 case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; 9255 case OP_GETATTR: GETATTR4res opgetattr; 9256 case OP_GETFH: GETFH4res opgetfh; 9257 case OP_LINK: LINK4res oplink; 9258 case OP_LOCK: LOCK4res oplock; 9259 case OP_LOCKT: LOCKT4res oplockt; 9260 case OP_LOCKU: LOCKU4res oplocku; 9261 case OP_LOOKUP: LOOKUP4res oplookup; 9262 case OP_LOOKUPP: LOOKUPP4res oplookupp; 9263 case OP_NVERIFY: NVERIFY4res opnverify; 9264 case OP_OPEN: OPEN4res opopen; 9265 case OP_OPENATTR: OPENATTR4res opopenattr; 9266 case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; 9267 case OP_PUTFH: PUTFH4res opputfh; 9268 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 9269 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 9270 case OP_READ: READ4res opread; 9271 case OP_READDIR: READDIR4res opreaddir; 9272 case OP_READLINK: READLINK4res opreadlink; 9273 case OP_REMOVE: REMOVE4res opremove; 9274 case OP_RENAME: RENAME4res oprename; 9275 case OP_RENEW: RENEW4res oprenew; 9276 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 9277 case OP_SAVEFH: SAVEFH4res opsavefh; 9278 case OP_SECINFO: SECINFO4res opsecinfo; 9280 Draft Specification NFS version 4 Protocol December 1999 9282 case OP_SETATTR: SETATTR4res opsetattr; 9283 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 9284 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4res 9285 opsetclientid_confirm; 9286 case OP_VERIFY: VERIFY4res opverify; 9287 case OP_WRITE: WRITE4res opwrite; 9288 }; 9290 struct COMPOUND4args { 9291 utf8string tag; 9292 uint32_t minorversion; 9293 nfs_argop4 argarray<>; 9294 }; 9296 struct COMPOUND4res { 9297 nfsstat4 status; 9298 utf8string tag; 9299 nfs_resop4 resarray<>; 9300 }; 9302 /* 9303 * Remote file service routines 9304 */ 9305 program NFS4_PROGRAM { 9306 version NFS_V4 { 9307 void 9308 NFSPROC4_NULL(void) = 0; 9310 COMPOUND4res 9311 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 9313 } = 4; 9314 } = 100003; 9316 /* 9317 * NFS4 Callback Procedure Definitions and Program 9318 */ 9320 /* 9321 * CB_GETATTR: Get Current Attributes 9322 */ 9323 struct CB_GETATTR4args { 9324 nfs_fh4 fh; 9325 bitmap4 attr_request; 9326 }; 9328 Draft Specification NFS version 4 Protocol December 1999 9330 struct CB_GETATTR4resok { 9331 fattr4 obj_attributes; 9332 }; 9334 union CB_GETATTR4res switch (nfsstat4 status) { 9335 case NFS4_OK: 9336 CB_GETATTR4resok resok4; 9337 default: 9338 void; 9339 }; 9341 /* 9342 * CB_RECALL: Recall an Open Delegation 9343 */ 9344 struct CB_RECALL4args { 9345 stateid4 stateid; 9346 bool truncate; 9347 nfs_fh4 fh; 9348 }; 9350 struct CB_RECALL4res { 9351 nfsstat4 status; 9352 }; 9354 /* 9355 * Various definitions for CB_COMPOUND 9356 */ 9357 enum nfs_cb_opnum4 { 9358 OP_CB_GETATTR = 3, 9359 OP_CB_RECALL = 4 9360 }; 9362 union nfs_cb_argop4 switch (unsigned argop) { 9363 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 9364 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 9365 }; 9367 union nfs_cb_resop4 switch (unsigned resop){ 9368 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 9369 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 9370 }; 9372 struct CB_COMPOUND4args { 9373 utf8string tag; 9374 uint32_t minorversion; 9375 nfs_cb_argop4 argarray<>; 9376 }; 9378 Draft Specification NFS version 4 Protocol December 1999 9380 struct CB_COMPOUND4res { 9381 nfsstat4 status; 9382 utf8string tag; 9383 nfs_cb_resop4 resarray<>; 9384 }; 9386 /* 9387 * Program number is in the transient range since the client 9388 * will assign the exact transient program number and provide 9389 * that to the server via the SETCLIENTID operation. 9390 */ 9391 program NFS4_CALLBACK { 9392 version NFS_CB { 9393 void 9394 CB_NULL(void) = 0; 9395 CB_COMPOUND4res 9396 CB_COMPOUND(CB_COMPOUND4args) = 1; 9397 } = 1; 9398 } = 40000000; 9400 Draft Specification NFS version 4 Protocol December 1999 9402 18. Bibliography 9404 [Gray] 9405 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 9406 for Distributed File Cache Consistency," Proceedings of the Twelfth 9407 Symposium on Operating Systems Principles, p. 202-210, December 1989. 9409 [Juszczak] 9410 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 9411 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 9412 CA, June 1990, pages 53-63. Describes reply cache implementation 9413 that avoids work in the server by handling duplicate requests. More 9414 important, though listed as a side-effect, the reply cache aids in 9415 the avoidance of destructive non-idempotent operation re-application 9416 -- improving correctness. 9418 [Kazar] 9419 Kazar, Michael Leon, "Synchronization and Caching Issues in the 9420 Andrew File System," USENIX Conference Proceedings, USENIX 9421 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 9422 description of the cache consistency scheme in AFS. Contrasted with 9423 other distributed file systems. 9425 [Macklem] 9426 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 9427 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 9428 Association, Berkeley, CA, January 1991. Describes performance work 9429 in tuning the 4.3BSD Reno NFS implementation. Describes performance 9430 improvement (reduced CPU loading) through elimination of data copies. 9432 [Mogul] 9433 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 9434 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 9435 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 9436 lease-based scheme for recovering state of consistency protocol. 9438 [Nowicki] 9439 Nowicki, Bill, "Transport Issues in the Network File System," ACM 9440 SIGCOMM newsletter Computer Communication Review, April 1989. A 9441 brief description of the basis for the dynamic retransmission work. 9443 Draft Specification NFS version 4 Protocol December 1999 9445 [Pawlowski] 9446 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 9447 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 9448 Conf. Proc., (1989) Description of an NFS server implementation for 9449 IBM's MVS operating system. 9451 [RFC1094] 9452 Sun Microsystems, Inc., "NFS: Network File System Protocol 9453 Specification", RFC1094, March 1989. 9455 http://www.ietf.org/rfc/rfc1094.txt 9457 [RFC1345] 9458 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 9459 Rationel Almen Planlaegning, June 1992. 9461 http://www.ietf.org/rfc/rfc1345.txt 9463 [RFC1700] 9464 Reynolds, J., Postel, J., "Assigned Numbers", RFC1700, ISI, October 9465 1994 9467 http://www.ietf.org/rfc/rfc1700.txt 9469 [RFC1813] 9470 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 9471 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 9473 http://www.ietf.org/rfc/rfc1813.txt 9475 [RFC1831] 9476 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 9477 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 9479 http://www.ietf.org/rfc/rfc1831.txt 9481 [RFC1832] 9482 Srinivasan, R., "XDR: External Data Representation Standard", 9483 RFC1832, Sun Microsystems, Inc., August 1995. 9485 http://www.ietf.org/rfc/rfc1832.txt 9487 Draft Specification NFS version 4 Protocol December 1999 9489 [RFC1833] 9490 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 9491 Sun Microsystems, Inc., August 1995. 9493 http://www.ietf.org/rfc/rfc1833.txt 9495 [RFC2025] 9496 Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", RFC2025, 9497 Bell-Northern Research, October 1996. 9499 http://www.ietf.org/rfc/rfc2026.txt 9501 [RFC2054] 9502 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 9503 Microsystems, Inc., October 1996 9505 http://www.ietf.org/rfc/rfc2054.txt 9507 [RFC2055] 9508 Callaghan, B., "WebNFS Server Specification", RFC2054, Sun 9509 Microsystems, Inc., October 1996 9511 http://www.ietf.org/rfc/rfc2055.txt 9513 [RFC2078] 9514 Linn, J., "Generic Security Service Application Program Interface, 9515 Version 2", RFC2078, OpenVision Technologies, January 1997. 9517 http://www.ietf.org/rfc/rfc2078.txt 9519 [RFC2152] 9520 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 9521 RFC2152, Apple Computer, Inc., May 1997 9523 http://www.ietf.org/rfc/rfc2152.txt 9525 [RFC2203] 9526 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 9527 RFC2203, Sun Microsystems, Inc., August 1995. 9529 http://www.ietf.org/rfc/rfc2203.txt 9531 Draft Specification NFS version 4 Protocol December 1999 9533 [RFC2279] 9534 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 9535 Alis Technologies, January 1998. 9537 http://www.ietf.org/rfc/rfc2279.txt 9539 [RFC2623] 9540 Eisler, M., "NFS Version 2 and Version 3 Security Issues and the NFS 9541 Protocol's Use of RPCSEC_GSS and Kerberos V5", RFC2623, Sun 9542 Microsystems, June 1999 9544 http://www.ietf.org/rfc/rfc2623.txt 9546 [RFC2624] 9547 Shepler, S., "NFS Version 4 Design Considerations", RFC2624, Sun 9548 Microsystems, June 1999 9550 http://www.ietf.org/rfc/rfc2624.txt 9552 [Sandberg] 9553 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 9554 and Implementation of the Sun Network Filesystem," USENIX Conference 9555 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 9556 basic paper describing the SunOS implementation of the NFS version 2 9557 protocol, and discusses the goals, protocol specification and trade- 9558 offs. 9560 [Srinivasan] 9561 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 9562 Performance of Cache Consistency Protocols", WRL Research Report 9563 89/5, Digital Equipment Corporation Western Research Laboratory, 100 9564 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 9565 the effect of applying a Sprite-like consistency protocol applied to 9566 standard NFS. The issues of recovery in a stateful environment are 9567 covered in [Mogul]. 9569 [Unicode1] 9570 "Unicode Technical Report #8 - The Unicode Standard, Version 2.1", 9571 Unicode, Inc., The Unicode Consortium, P.O. Box 700519, San Jose, CA 9572 95710-0519 USA, September 1998 9574 http://www.unicode.org/unicode/reports/tr8.html 9576 Draft Specification NFS version 4 Protocol December 1999 9578 [Unicode2] 9579 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 9580 700519, San Jose, CA 95710-0519 USA, October 1998 9582 http://www.unicode.org/unicode/standard/unsupported.html 9584 [XNFS] 9585 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 9586 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 9587 1-85912-184-5, February 1998. 9589 HTML version available: http://www.opengroup.org 9591 Draft Specification NFS version 4 Protocol December 1999 9593 19. Authors and Contributors 9595 General feedback related to this document should be directed to: 9597 nfsv4-wg@sunroof.eng.sun.com 9599 or the editor. 9601 19.1. Editor's Address 9603 Spencer Shepler 9604 Sun Microsystems, Inc. 9605 7808 Moonflower Drive 9606 Austin, Texas 78750 9608 Phone: +1 512-349-9376 9609 E-mail: shepler@eng.sun.com 9611 19.2. Authors' Addresses 9613 Carl Beame 9614 Hummingbird Communications Ltd. 9616 E-mail: beame@bws.com 9618 Brent Callaghan 9619 Sun Microsystems, Inc. 9620 901 San Antonio Road 9621 Palo Alto, CA 94303 9623 Phone: +1 650-786-5067 9624 E-mail: brent.callaghan@eng.sun.com 9626 Mike Eisler 9627 Sun Microsystems, Inc. 9628 5565 Wilson Road 9629 Colorado Springs, CO 80919 9631 Phone: +1 719-599-9026 9632 E-mail: mre@eng.sun.com 9634 Dave Noveck 9635 Network Appliance 9636 495 East Java Drive 9637 Sunnyvale, CA 94089 9639 Draft Specification NFS version 4 Protocol December 1999 9641 Phone: +1 781-861-9291 9642 E-mail: dave.noveck@netapp.com 9644 David Robinson 9645 Sun Microsystems, Inc. 9646 901 San Antonio Road 9647 Palo Alto, CA 94303 9649 Phone: +1 650-786-5088 9650 E-mail: david.robinson@eng.sun.com 9652 Robert Thurlow 9653 Sun Microsystems, Inc. 9654 901 San Antonio Road 9655 Palo Alto, CA 94303 9657 Phone: +1 650-786-5096 9658 E-mail: robert.thurlow@eng.sun.com 9660 Draft Specification NFS version 4 Protocol December 1999 9662 20. Full Copyright Statement 9664 "Copyright (C) The Internet Society (1999). All Rights Reserved. 9666 This document and translations of it may be copied and furnished to 9667 others, and derivative works that comment on or otherwise explain it 9668 or assist in its implementation may be prepared, copied, published 9669 and distributed, in whole or in part, without restriction of any 9670 kind, provided that the above copyright notice and this paragraph are 9671 included on all such copies and derivative works. However, this 9672 document itself may not be modified in any way, such as by removing 9673 the copyright notice or references to the Internet Society or other 9674 Internet organizations, except as needed for the purpose of 9675 developing Internet standards in which case the procedures for 9676 copyrights defined in the Internet Standards process must be 9677 followed, or as required to translate it into languages other than 9678 English. 9680 The limited permissions granted above are perpetual and will not be 9681 revoked by the Internet Society or its successors or assigns. 9683 This document and the information contained herein is provided on an 9684 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 9685 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 9686 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 9687 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 9688 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."