idnits 2.17.1 draft-ietf-nfsv4-06.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 1 longer page, the longest (page 154) being 61 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 251 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** 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 609 has weird spacing: '...ned int uin...' == Line 613 has weird spacing: '...d hyper uint6...' == Line 678 has weird spacing: '...8string typ...' == Line 763 has weird spacing: '...8string ser...' == Line 829 has weird spacing: '...ned int cb_pr...' == (37 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The reader may be wondering why there are three FH4_VOL* bits and why FH4_VOLATILE_ANY is exclusive of FH4_VOL_MIGRATION and FH4_VOL_RENAME. If the a filehandle is normally persistent but cannot persist across a file set migration, then the presence of the FH4_VOL_MIGRATION or FH4_VOL_RENAME tells the client that it can treat the file handle as persistent for purposes of maintaining a file name to file handle cache, except for the specific event described by the bit. However, FH4_VOLATILE_ANY tells the client that it should not maintain such a cache for unopened files. A server MUST not present FH4_VOLATILE_ANY with FH4_VOL_MIGRATION or FH4_VOL_RENAME as this will lead to confusion. FH4_VOLATILE_ANY implies that the file handle will expire upon migration or rename, in addition to other events. -- 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 (February 2000) is 8837 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 10338 looks like a reference -- Missing reference section? 'RFC1813' on line 10356 looks like a reference -- Missing reference section? 'RFC1831' on line 10362 looks like a reference -- Missing reference section? 'RFC1832' on line 10370 looks like a reference -- Missing reference section? 'RFC2623' on line 10432 looks like a reference -- Missing reference section? 'RFC1964' on line 916 looks like a reference -- Missing reference section? 'RFCXXXX' on line 10445 looks like a reference -- Missing reference section? 'RFC2078' on line 10400 looks like a reference -- Missing reference section? 'RFC2203' on line 10414 looks like a reference -- Missing reference section? 'RFC1700' on line 10350 looks like a reference -- Missing reference section? 'RFC1833' on line 10376 looks like a reference -- Missing reference section? 'RFC2581' on line 882 looks like a reference -- Missing reference section? 'RFC2025' on line 10382 looks like a reference -- Missing reference section? 'RFC2054' on line 10388 looks like a reference -- Missing reference section? 'RFC2055' on line 10394 looks like a reference -- Missing reference section? 'RFC2624' on line 10439 looks like a reference -- Missing reference section? 'XNFS' on line 10484 looks like a reference -- Missing reference section? '4' on line 2505 looks like a reference -- Missing reference section? 'Juszczak' on line 10296 looks like a reference -- Missing reference section? 'ISO10646' on line 10291 looks like a reference -- Missing reference section? 'RFC2277' on line 10420 looks like a reference -- Missing reference section? 'RFC1345' on line 10344 looks like a reference -- Missing reference section? 'RFC2279' on line 10426 looks like a reference -- Missing reference section? 'RFC2152' on line 10406 looks like a reference -- Missing reference section? 'Unicode1' on line 10471 looks like a reference -- Missing reference section? 'Unicode2' on line 10478 looks like a reference -- Missing reference section? 'Gray' on line 10286 looks like a reference -- Missing reference section? 'Kazar' on line 10305 looks like a reference -- Missing reference section? 'Macklem' on line 10312 looks like a reference -- Missing reference section? 'Mogul' on line 10469 looks like a reference -- Missing reference section? 'Nowicki' on line 10327 looks like a reference -- Missing reference section? 'Pawlowski' on line 10332 looks like a reference -- Missing reference section? 'Sandberg' on line 10451 looks like a reference -- Missing reference section? 'Srinivasan' on line 10462 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 11 warnings (==), 37 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-06.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 February 2000 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 protocol versions 2 [RFC1094] and 3 [RFC1813]. 45 Draft Specification NFS version 4 Protocol February 2000 47 Unlike earlier versions, the NFS version 4 protocol supports 48 traditional file access while integrating support for file locking 49 and the mount protocol. In addition, support for strong security 50 (and its negotiation), compound operations, client caching, and 51 internationalization have been added. Of course, attention has been 52 applied to making NFS version 4 operate well in an Internet 53 environment. 55 Copyright 57 Copyright (C) The Internet Society (1999). All Rights Reserved. 59 Key Words 61 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 62 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 63 document are to be interpreted as described in RFC 2119. 65 Draft Specification NFS version 4 Protocol February 2000 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 70 1.1. Overview of NFS Version 4 Features . . . . . . . . . . . . 7 71 1.1.1. RPC and Security . . . . . . . . . . . . . . . . . . . . 8 72 1.1.2. Procedure and Operation Structure . . . . . . . . . . . 8 73 1.1.3. File System Model . . . . . . . . . . . . . . . . . . . 9 74 1.1.3.1. Filehandle Types . . . . . . . . . . . . . . . . . . . 9 75 1.1.3.2. Attribute Types . . . . . . . . . . . . . . . . . . 10 76 1.1.3.3. File System Replication and Migration . . . . . . . 10 77 1.1.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . . 11 78 1.1.5. File locking . . . . . . . . . . . . . . . . . . . . . 11 79 1.1.6. Client Caching and Delegation . . . . . . . . . . . . 11 80 1.2. General Definitions . . . . . . . . . . . . . . . . . . 12 81 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . 14 82 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 14 83 2.2. Structured Data Types . . . . . . . . . . . . . . . . . 15 84 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . 20 85 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 20 86 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 20 87 3.2.1. Security mechanisms for NFS version 4 . . . . . . . . 20 88 3.2.1.1. Kerberos V5 as security triple . . . . . . . . . . . 21 89 3.2.1.2. LIPKEY as a security triple . . . . . . . . . . . . 21 90 3.2.1.3. SPKM-3 as a security triple . . . . . . . . . . . . 22 91 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 23 92 3.3.1. Security Error . . . . . . . . . . . . . . . . . . . . 23 93 3.3.2. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 23 94 3.4. Callback RPC Authentication . . . . . . . . . . . . . . 23 95 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . 25 96 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 25 97 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . . 25 98 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . . 26 99 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 26 100 4.2.1. General Properties of a Filehandle . . . . . . . . . . 27 101 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . . 27 102 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 28 103 4.2.4. One Method of Constructing a Volatile Filehandle . . . 29 104 4.3. Client Recovery from Filehandle Expiration . . . . . . . 30 105 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 31 106 5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 32 107 5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 32 108 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 32 109 5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 34 110 5.5. Recommended Attributes - Definitions . . . . . . . . . . 36 111 5.6. Interpreting owner and owner_group . . . . . . . . . . . 41 112 5.7. Quota Attributes . . . . . . . . . . . . . . . . . . . . 42 113 5.8. Access Control Lists . . . . . . . . . . . . . . . . . . 43 114 5.8.1. ACE type . . . . . . . . . . . . . . . . . . . . . . . 44 116 Draft Specification NFS version 4 Protocol February 2000 118 5.8.2. ACE flag . . . . . . . . . . . . . . . . . . . . . . . 44 119 5.8.3. ACE Access Mask . . . . . . . . . . . . . . . . . . . 46 120 5.8.4. ACE who . . . . . . . . . . . . . . . . . . . . . . . 47 121 6. File System Migration and Replication . . . . . . . . . . 48 122 6.1. Replication . . . . . . . . . . . . . . . . . . . . . . 48 123 6.2. Migration . . . . . . . . . . . . . . . . . . . . . . . 48 124 6.3. Interpretation of the fs_locations Attribute . . . . . . 49 125 6.4. Filehandle Recovery for Migration or Replication . . . . 50 126 7. NFS Server Name Space . . . . . . . . . . . . . . . . . . 51 127 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 51 128 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 51 129 7.3. Server Pseudo File System . . . . . . . . . . . . . . . 52 130 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 52 131 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 52 132 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 53 133 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 53 134 7.8. Security Policy and Name Space Presentation . . . . . . 53 135 8. File Locking and Share Reservations . . . . . . . . . . . 55 136 8.1. Locking . . . . . . . . . . . . . . . . . . . . . . . . 55 137 8.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 56 138 8.1.2. Server Release of Clientid . . . . . . . . . . . . . . 57 139 8.1.3. nfs_lockowner and stateid Definition . . . . . . . . . 58 140 8.1.4. Use of the stateid . . . . . . . . . . . . . . . . . . 59 141 8.1.5. Sequencing of Lock Requests . . . . . . . . . . . . . 60 142 8.1.6. Recovery from Replayed Requests . . . . . . . . . . . 60 143 8.1.7. Releasing nfs_lockowner State . . . . . . . . . . . . 61 144 8.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 61 145 8.3. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 62 146 8.4. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 63 147 8.5. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 63 148 8.5.1. Client Failure and Recovery . . . . . . . . . . . . . 64 149 8.5.2. Server Failure and Recovery . . . . . . . . . . . . . 64 150 8.5.3. Network Partitions and Recovery . . . . . . . . . . . 66 151 8.6. Recovery from a Lock Request Timeout or Abort . . . . . 67 152 8.7. Server Revocation of Locks . . . . . . . . . . . . . . . 68 153 8.8. Share Reservations . . . . . . . . . . . . . . . . . . . 69 154 8.9. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 70 155 8.10. Open Upgrade and Downgrade . . . . . . . . . . . . . . 70 156 8.11. Short and Long Leases . . . . . . . . . . . . . . . . . 71 157 8.12. Clocks and Calculating Lease Expiration . . . . . . . . 71 158 8.13. Migration, Replication and State . . . . . . . . . . . 72 159 8.13.1. Migration and State . . . . . . . . . . . . . . . . . 72 160 8.13.2. Replication and State . . . . . . . . . . . . . . . . 73 161 8.13.3. Notification of Migrated Lease . . . . . . . . . . . 73 162 9. Client-Side Caching . . . . . . . . . . . . . . . . . . . 75 163 9.1. Performance Challenges for Client-Side Caching . . . . . 75 164 9.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 76 165 9.2.1. Delegation Recovery . . . . . . . . . . . . . . . . . 78 167 Draft Specification NFS version 4 Protocol February 2000 169 9.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 79 170 9.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . . 80 171 9.3.2. Data Caching and File Locking . . . . . . . . . . . . 80 172 9.3.3. Data Caching and Mandatory File Locking . . . . . . . 82 173 9.3.4. Data Caching and File Identity . . . . . . . . . . . . 82 174 9.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 83 175 9.4.1. Open Delegation and Data Caching . . . . . . . . . . . 86 176 9.4.2. Open Delegation and File Locks . . . . . . . . . . . . 87 177 9.4.3. Recall of Open Delegation . . . . . . . . . . . . . . 87 178 9.4.4. Delegation Revocation . . . . . . . . . . . . . . . . 89 179 9.5. Data Caching and Revocation . . . . . . . . . . . . . . 89 180 9.5.1. Revocation Recovery for Write Open Delegation . . . . 90 181 9.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 91 182 9.7. Name Caching . . . . . . . . . . . . . . . . . . . . . . 92 183 9.8. Directory Caching . . . . . . . . . . . . . . . . . . . 93 184 10. Minor Versioning . . . . . . . . . . . . . . . . . . . . 95 185 11. Internationalization . . . . . . . . . . . . . . . . . . 98 186 11.1. Universal Versus Local Character Sets . . . . . . . . . 98 187 11.2. Overview of Universal Character Set Standards . . . . . 99 188 11.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 100 189 11.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 101 190 11.5. Normalization . . . . . . . . . . . . . . . . . . . . . 101 191 12. Error Definitions . . . . . . . . . . . . . . . . . . . . 103 192 13. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 108 193 13.1. Compound Procedure . . . . . . . . . . . . . . . . . . 108 194 13.2. Evaluation of a Compound Request . . . . . . . . . . . 109 195 13.3. Synchronous Modifying Operations . . . . . . . . . . . 109 196 13.4. Operation Values . . . . . . . . . . . . . . . . . . . 110 197 14. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 111 198 14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 111 199 14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 112 200 14.2.1. Operation 3: ACCESS - Check Access Rights . . . . . . 115 201 14.2.2. Operation 4: CLOSE - Close File . . . . . . . . . . . 119 202 14.2.3. Operation 5: COMMIT - Commit Cached Data . . . . . . 121 203 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 124 204 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 205 Recovery . . . . . . . . . . . . . . . . . . . . . . 127 206 14.2.6. Operation 8: DELEGRETURN - Return Delegation . . . . 128 207 14.2.7. Operation 9: GETATTR - Get Attributes . . . . . . . . 129 208 14.2.8. Operation 10: GETFH - Get Current Filehandle . . . . 131 209 14.2.9. Operation 11: LINK - Create Link to a File . . . . . 133 210 14.2.10. Operation 12: LOCK - Create Lock . . . . . . . . . . 135 211 14.2.11. Operation 13: LOCKT - Test For Lock . . . . . . . . 138 212 14.2.12. Operation 14: LOCKU - Unlock File . . . . . . . . . 140 213 14.2.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . 142 214 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory . . 145 215 14.2.15. Operation 17: NVERIFY - Verify Difference in 216 Attributes . . . . . . . . . . . . . . . . . . . . . 147 218 Draft Specification NFS version 4 Protocol February 2000 220 14.2.16. Operation 18: OPEN - Open a Regular File . . . . . . 149 221 14.2.17. Operation 19: OPENATTR - Open Named Attribute 222 Directory . . . . . . . . . . . . . . . . . . . . . 158 223 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . 160 224 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access163 225 14.2.20. Operation 22: PUTFH - Set Current Filehandle . . . . 165 226 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle . . . 166 227 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle . . . 167 228 14.2.23. Operation 25: READ - Read from File . . . . . . . . 168 229 14.2.24. Operation 26: READDIR - Read Directory . . . . . . . 171 230 14.2.25. Operation 27: READLINK - Read Symbolic Link . . . . 175 231 14.2.26. Operation 28: REMOVE - Remove Filesystem Object . . 177 232 14.2.27. Operation 29: RENAME - Rename Directory Entry . . . 179 233 14.2.28. Operation 30: RENEW - Renew a Lease . . . . . . . . 182 234 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle . 184 235 14.2.30. Operation 32: SAVEFH - Save Current Filehandle . . . 186 236 14.2.31. Operation 33: SECINFO - Obtain Available Security . 187 237 14.2.32. Operation 34: SETATTR - Set Attributes . . . . . . . 189 238 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid . . . 192 239 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 194 240 14.2.35. Operation 37: VERIFY - Verify Same Attributes . . . 196 241 14.2.36. Operation 38: WRITE - Write to File . . . . . . . . 198 242 15. NFS Version 4 Callback Procedures . . . . . . . . . . . . 203 243 15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 203 244 15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 204 245 15.2.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . 206 246 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation . 208 247 16. Security Considerations . . . . . . . . . . . . . . . . . 210 248 17. IANA Considerations . . . . . . . . . . . . . . . . . . . 211 249 17.1. Named Attribute Definition . . . . . . . . . . . . . . 211 250 18. RPC definition file . . . . . . . . . . . . . . . . . . . 212 251 19. Bibliography . . . . . . . . . . . . . . . . . . . . . . 244 252 20. Authors . . . . . . . . . . . . . . . . . . . . . . . . . 249 253 20.1. Editor's Address . . . . . . . . . . . . . . . . . . . 249 254 20.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 249 255 21. Full Copyright Statement . . . . . . . . . . . . . . . . 251 257 Draft Specification NFS version 4 Protocol February 2000 259 1. Introduction 261 The NFS version 4 protocol is a further revision of the NFS protocol 262 defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains 263 the essential characteristics of previous versions: design for easy 264 recovery, independent of transport protocols, operating systems and 265 filesystems, simplicity, and good performance. The NFS version 4 266 revision has the following goals: 268 o Improved access and good performance on the Internet. 270 The protocol is designed to transit firewalls easily, perform 271 well where latency is high and bandwidth is low, and scale to 272 very large numbers of clients per server. 274 o Strong security with negotiation built into the protocol. 276 The protocol builds on the work of the ONCRPC working group in 277 supporting the RPCSEC_GSS protocol. Additionally, the NFS 278 version 4 protocol provides a mechanism to allow clients and 279 servers the ability to negotiate security and require clients 280 and servers to support a minimal set of security schemes. 282 o Good cross-platform interoperability. 284 The protocol features a file system model that provides a 285 useful, common set of features that does not unduly favor one 286 file system or operating system over another. 288 o Designed for protocol extensions. 290 The protocol is designed to accept standard extensions that do 291 not compromise backward compatibility. 293 1.1. Overview of NFS Version 4 Features 295 To provide a reasonable context for the reader, the major features of 296 NFS version 4 protocol will be reviewed in brief. This will be done 297 to provide an appropriate context for both the reader who is familiar 298 with the previous versions of the NFS protocol and the reader that is 299 new to the NFS protocols. For the reader new to the NFS protocols, 300 there is still a fundamental knowledge that is expected. The reader 301 should be familiar with the XDR and RPC protocols as described in 303 Draft Specification NFS version 4 Protocol February 2000 305 [RFC1831] and [RFC1832]. A basic knowledge of file systems and 306 distributed file systems is expected as well. 308 1.1.1. RPC and Security 310 As with previous versions of NFS, the External Data Representation 311 (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS 312 version 4 protocol are those defined in [RFC1831] and [RFC1832]. To 313 meet end to end security requirements, the RPCSEC_GSS framework 314 [RFC2623] will be used to extend the basic RPC security. With the 315 use of RPCSEC_GSS, various mechanisms can be provided to offer 316 authentication, integrity, and privacy to the NFS version 4 protocol. 317 Kerberos V5 will be used as described in [RFC1964] to provide one 318 security framework. The LIPKEY GSS-API mechanism described in 319 [RFCXXXX] will be used to provide for the use of user password and 320 server public key by the NFS version 4 protocol. With the use of 321 RPCSEC_GSS, other mechanisms may also be specified and used for NFS 322 version 4 security. 324 To enable in-band security negotiation, the NFS version 4 protocol 325 has added a new operation which provides the client a method of 326 querying the server about its policies regarding which security 327 mechanisms must be used for access to the server's file system 328 resources. With this, the client can securely match the security 329 mechanism that meets the policies specified at both the client and 330 server. 332 1.1.2. Procedure and Operation Structure 334 A significant departure from the previous versions of the NFS 335 protocol is the introduction of the COMPOUND procedure. For the NFS 336 version 4 protocol, there are two RPC procedures, NULL and COMPOUND. 337 The COMPOUND procedure is defined in terms of operations and these 338 operations correspond more closely to the traditional NFS procedures. 339 With the use of the COMPOUND procedure, the client is able to build 340 simple or complex requests. These COMPOUND requests allow for a 341 reduction in the number of RPCs needed for logical file system 342 operations. For example, without previous contact with a server a 343 client will be able to read data from a file in one request by 344 combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. 345 With previous versions of the NFS protocol, this type of single 346 request was not possible. 348 The model used for COMPOUND is very simple. There is no logical OR 349 or ANDing of operations. The operations combined within a COMPOUND 350 request are evaluated in order by the server. Once an operation 352 Draft Specification NFS version 4 Protocol February 2000 354 returns a failing result, the evaluation ends and the results of all 355 evaluated operations are returned to the client. 357 The NFS version 4 protocol continues to have the client refer to a 358 file or directory at the server by a "filehandle". The COMPOUND 359 procedure has a method of passing a filehandle from one operation to 360 another within the sequence of operations. There is a concept of a 361 "current filehandle" and "saved filehandle". Most operations use the 362 "current filehandle" as the file system object to operate upon. The 363 "saved filehandle" is used as temporary filehandle storage within a 364 COMPOUND procedure as well as an additional operand for certain 365 operations. 367 1.1.3. File System Model 369 The general file system model used for the NFS version 4 protocol is 370 the same as previous versions. The server file system is 371 hierarchical with the regular files contained within being treated as 372 opaque byte streams. In a slight departure, file and directory names 373 are encoded with UTF-8 to deal with the basics of 374 internationalization. 376 The NFS version 4 protocol does not require a separate protocol to 377 provide for the initial mapping between path name and filehandle. 378 Instead of using the older MOUNT protocol for this mapping, the 379 server provides a ROOT filehandle that represents the logical root or 380 top of the file system tree provided by the server. The server 381 provides multiple file systems by glueing them together with pseudo 382 file systems. These pseudo file systems provide for potential gaps 383 in the path names between real file systems. 385 1.1.3.1. Filehandle Types 387 In previous versions of the NFS protocol, the filehandle provided by 388 the server was guaranteed to be valid or persistent for the lifetime 389 of the file system object to which it referred. For some server 390 implementations, this persistence requirement has been difficult to 391 meet. For the NFS version 4 protocol, this requirement has been 392 relaxed by introducing another type of filehandle, volatile. With 393 persistent and volatile filehandle types, the server implementation 394 can match the abilities of the file system at the server along with 395 the operating environment. The client will have knowledge of the 396 type of filehandle being provided by the server and can be prepared 397 to deal with the semantics of each. 399 Draft Specification NFS version 4 Protocol February 2000 401 1.1.3.2. Attribute Types 403 The NFS version 4 protocol introduces three classes of file system or 404 file attributes. Like the additional filehandle type, the 405 classification of file attributes has been done to ease server 406 implementations along with extending the overall functionality of the 407 NFS protocol. This attribute model is structured to be extensible 408 such that new attributes can be introduced in minor revisions of the 409 protocol without requiring significant rework. 411 The three classifications are: mandatory, recommended and named 412 attributes. This is a significant departure from the previous 413 attribute model used in the NFS protocol. Previously, the attributes 414 for the file system and file objects were a fixed set of mainly Unix 415 attributes. If the server or client did not support a particular 416 attribute, it would have to simulate the attribute the best it could. 418 Mandatory attributes are the minimal set of file or file system 419 attributes that must be provided by the server and must be properly 420 represented by the server. Recommended attributes represent 421 different file system types and operating environments. The 422 recommended attributes will allow for better interoperability and the 423 inclusion of more operating environments. The mandatory and 424 recommended attribute sets are traditional file or file system 425 attributes. The third type of attribute is the named attribute. A 426 named attribute is an opaque byte stream that is associated with a 427 directory or file and referred to by a string name. Named attributes 428 are meant to be used by client applications as a method to associate 429 application specific data with a regular file or directory. 431 One significant addition to the recommended set of file attributes is 432 the Access Control List (ACL) attribute. This attribute provides for 433 directory and file access control beyond the model used in previous 434 versions of the NFS protocol. The ACL definition allows for 435 specification of user and group level access control. 437 1.1.3.3. File System Replication and Migration 439 With the use of a special file attribute, the ability to migrate or 440 replicate server file systems is enabled within the protocol. The 441 file system locations attribute provides a method for the client to 442 probe the server about the location of a file system. In the event 443 of a migration of a file system, the client will receive an error 444 when operating on the file system and it can then query as to the new 445 file system location. Similar steps are used for replication, the 446 client is able to query the server for the multiple available 447 locations of a particular file system. From this information, the 449 Draft Specification NFS version 4 Protocol February 2000 451 client can use its own policies to access the appropriate file system 452 location. 454 1.1.4. OPEN and CLOSE 456 The NFS version 4 protocol introduces OPEN and CLOSE operations. The 457 OPEN operation provides a single point where file lookup, creation, 458 and share semantics can be combined. The CLOSE operation also 459 provides for the release of state accumulated by OPEN. 461 1.1.5. File locking 463 With the NFS version 4 protocol, the support for byte range file 464 locking is part of the NFS protocol. The file locking support is 465 structured so that an RPC callback mechanism is not required. This 466 is a departure from the previous versions of the NFS file locking 467 protocol, Network Lock Manager (NLM). The state associated with file 468 locks is maintained at the server under a lease-based model. The 469 server defines a single lease period for all state held by a NFS 470 client. If the client does not renew its lease within the defined 471 period, all state associated with the client's lease may be released 472 by the server. The client may renew its lease with use of the RENEW 473 operation or implicitly by use of other operations (primarily READ). 475 1.1.6. Client Caching and Delegation 477 The file, attribute, and directory caching for the NFS version 4 478 protocol is similar to previous versions. Attributes and directory 479 information are cached for a duration determined by the client. At 480 the end of a predefined timeout, the client will query the server to 481 see if the related file system object has been updated. 483 For file data, the client checks its cache validity when the file is 484 opened. A query is sent to the server to determine if the file has 485 been changed. Based on this information, the client determines if 486 the data cache for the file should kept or released. Also, when the 487 file is closed, any modified data is written to the server. 489 If an application wants to serialize access to file data, file 490 locking of the file data ranges in question should be used. 492 The major addition to NFS version 4 in the area of caching is the 493 ability of the server to delegate certain responsibilities to the 494 client. When the server grants a delegation for a file to a client, 495 the client is guaranteed certain semantics with respect to the 497 Draft Specification NFS version 4 Protocol February 2000 499 sharing of that file with other clients. At OPEN, the server may 500 provide the client either a read or write delegation for the file. 501 If the client is granted a read delegation, it is assured that no 502 other client has the ability to write to the file for the duration of 503 the delegation. If the client is granted a write delegation, the 504 client is assured that no other client has read or write access to 505 the file. 507 Delegations can be recalled by the server. If another client 508 requests access to the file in such a way that the access conflicts 509 with the granted delegation, the server is able to notify the initial 510 client and recall the delegation. This requires that a callback path 511 exist between the server and client. If this callback path does not 512 exist, then delegations can not be granted. The essence of a 513 delegation is that it allows the client to locally service operations 514 such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate 515 interaction with the server. 517 1.2. General Definitions 519 The following definitions are provided for the purpose of providing 520 an appropriate context for the reader. 522 Client The "client" is the entity that accesses the NFS server's 523 resources. The client may be an application which contains 524 the logic to access the NFS server directly. The client 525 may also be the traditional operating system client remote 526 file system services for a set of applications. 528 In the case of file locking the client is the entity that 529 maintains a set of locks on behalf of one or more 530 applications. This client is responsible for crash or 531 failure recovery for those locks it manages. 533 Note that multiple clients may share the same transport and 534 multiple clients may exist on the same network node. 536 Clientid A 64-bit quantity used as a unique, short-hand reference to 537 a client supplied Verifier and ID. The server is 538 responsible for supplying the Clientid. 540 Lease An interval of time defined by the server for which the 541 client is irrevokeably granted a lock. At the end of a 542 lease period the lock may be revoked if the lease has not 543 been extended. The lock must be revoked if a conflicting 544 lock has been granted after the lease interval. 546 Draft Specification NFS version 4 Protocol February 2000 548 All leases granted by a server have the same fixed 549 interval. 551 Lock The term "lock" is used to refer to both record (byte- 552 range) locks as well as file (share) locks unless 553 specifically stated otherwise. 555 Server The "Server" is the entity responsible for coordinating 556 client access to a set of file systems. 558 Stable Storage 559 NFS version 4 servers must be able to recover without data 560 loss from multiple power failures (including cascading 561 power failures, that is, several power failures in quick 562 succession), operating system failures, and hardware 563 failure of components other than the storage medium itself 564 (for example, disk, nonvolatile RAM). 566 Some examples of stable storage that are allowable for an 567 NFS server include: 569 1. Media commit of data, that is, the modified data has 570 been successfully written to the disk media, 571 for example, the disk platter. 573 2. An immediate reply disk drive with battery-backed 574 on-drive intermediate storage or uninterruptible power 575 system (UPS). 577 3. Server commit of data with battery-backed intermediate 578 storage and recovery software. 580 4. Cache commit with uninterruptible power system (UPS) 581 and recovery software. 583 Stateid A 64-bit quantity returned by a server that uniquely 584 defines the locking state granted by the server for a 585 specific lock owner for a specific file. 587 Stateids composed of all bits 0 or all bits 1 have special 588 meaning and are reserved values. 590 Verifier A 64-bit quantity generated by the client that the server 591 can use to determine if the client has restarted and lost 592 all previous lock state. 594 Draft Specification NFS version 4 Protocol February 2000 596 2. Protocol Data Types 598 The syntax and semantics to describe the data types of the NFS 599 version 4 protocol are defined in the XDR [RFC1832] and RPC [RFC1831] 600 documents. The next sections build upon the XDR data types to define 601 types and structures specific to this protocol. 603 2.1. Basic Data Types 605 Data Type Definition 606 _____________________________________________________________________ 607 int32_t typedef int int32_t; 609 uint32_t typedef unsigned int uint32_t; 611 int64_t typedef hyper int64_t; 613 uint64_t typedef unsigned hyper uint64_t; 615 attrlist4 typedef opaque attrlist4<>; 616 Used for file/directory attributes 618 bitmap4 typedef uint32_t bitmap4<>; 619 Used in attribute array encoding. 621 changeid4 typedef uint64_t changeid4; 622 Used in definition of change_info 624 clientid4 typedef uint64_t clientid4; 625 Shorthand reference to client identification 627 component4 typedef utf8string component4; 628 Represents path name components 630 count4 typedef uint32_t count4; 631 Various count parameters (READ, WRITE, COMMIT) 633 length4 typedef uint64_t length4; 634 Describes LOCK lengths 636 linktext4 typedef utf8string linktext4; 637 Symbolic link contents 639 mode4 typedef uint32_t mode4; 640 Mode attribute data type 642 nfs_cookie4 typedef uint64_t nfs_cookie4; 643 Opaque cookie value for READDIR 645 Draft Specification NFS version 4 Protocol February 2000 647 nfs_fh4 typedef opaque nfs_fh4; 648 Filehandle definition; NFS4_FHSIZE is defined as 128 650 nfs_ftype4 enum nfs_ftype4; 651 Various defined file types 653 nfsstat4 enum nfsstat4; 654 Return value for operations 656 offset4 typedef uint64_t offset4; 657 Various offset designations (READ, WRITE, LOCK, COMMIT) 659 pathname4 typedef component4 pathname4<>; 660 Represents path name for LOOKUP, OPEN and others 662 qop4 typedef uint32_t qop4; 663 Quality of protection designation in SECINFO 665 sec_oid4 typedef opaque sec_oid4<>; 666 Security Object Identifier 667 The sec_oid4 data type is not really opaque. 668 Instead contains an ASN.1 OBJECT IDENTIFIER as used 669 by GSS-API in the mech_type argument to 670 GSS_Init_sec_context. See [RFC2078] for details. 672 seqid4 typedef uint32_t seqid4; 673 Sequence identifier used for file locking 675 stateid4 typedef uint64_t stateid4; 676 State identifier used for file locking and delegation 678 utf8string typedef opaque utf8string<>; 679 UTF-8 encoding for strings 681 verifier4 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 682 Verifier used for various operations (COMMIT, CREATE, 683 OPEN, READDIR, SETCLIENTID, WRITE) 684 NFS4_VERIFIER_SIZE is defined as 8 686 2.2. Structured Data Types 688 nfstime4 689 struct nfstime4 { 690 int64_t seconds; 691 uint32_t nseconds; 693 Draft Specification NFS version 4 Protocol February 2000 695 } 697 The nfstime4 structure gives the number of seconds and 698 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 699 Universal Time (UTC). Values greater than zero for the seconds 700 field denote dates after the 0 hour January 1, 1970. Values 701 less than zero for the seconds field denote dates before the 0 702 hour January 1, 1970. In both cases, the nseconds field is to 703 be added to the seconds field for the final time representation. 704 For example, if the time to be represented is one-half second 705 before 0 hour January 1, 1970, the seconds field would have a 706 value of negative one (-1) and the nseconds fields would have a 707 value of one-half second (500000000). Values greater than 708 999,999,999 for nseconds are considered invalid. 710 This data type is used to pass time and date information. A 711 server converts to and from local time when processing time 712 values, preserving as much accuracy as possible. If the 713 precision of timestamps stored for a file system object is less 714 than defined, loss of precision can occur. An adjunct time 715 maintenance protocol is recommended to reduce client and server 716 time skew. 718 time_how4 720 enum time_how4 { 721 SET_TO_SERVER_TIME4 = 0, 722 SET_TO_CLIENT_TIME4 = 1 723 }; 725 settime4 727 union settime4 switch (time_how4 set_it) { 728 case SET_TO_CLIENT_TIME4: 729 nfstime4 time; 730 default: 731 void; 732 }; 734 The above definitions are used as the attribute definitions to 735 set time values. If set_it is SET_TO_SERVER_TIME4, then the 736 server uses its local time for the time value. 738 specdata4 740 Draft Specification NFS version 4 Protocol February 2000 742 struct specdata4 { 743 uint32_t specdata1; 744 uint32_t specdata2; 745 }; 747 This data type represents additional information for the device 748 file types NF4CHR and NF4BLK. 750 fsid4 752 struct fsid4 { 753 uint64_t major; 754 uint64_t minor; 755 }; 757 This type is the file system identifier that is used as a 758 mandatory attribute. 760 fs_location4 762 struct fs_location4 { 763 utf8string server<>; 764 pathname4 rootpath; 765 }; 767 fs_locations4 769 struct fs_locations4 { 770 pathname4 fs_root; 771 fs_location4 locations<>; 772 }; 774 The fs_location4 and fs_locations4 data types are used for the 775 fs_locations recommended attribute which is used for migration 776 and replication support. 778 fattr4 780 struct fattr4 { 781 bitmap4 attrmask; 782 attrlist4 attr_vals; 783 }; 785 The fattr4 structure is used to represent file and directory 787 Draft Specification NFS version 4 Protocol February 2000 789 attributes. 791 The bitmap is a counted array of 32 bit integers used to contain 792 bit values. The position of the integer in the array that 793 contains bit n can be computed from the expression (n / 32) and 794 its bit within that integer is (n mod 32). 796 0 1 797 +-----------+-----------+-----------+-- 798 | count | 31 .. 0 | 63 .. 32 | 799 +-----------+-----------+-----------+-- 801 change_info4 803 struct change_info4 { 804 bool atomic; 805 changeid4 before; 806 changeid4 after; 807 }; 809 This structure is used with the CREATE, LINK, REMOVE, RENAME 810 operations to let the client know value of the change attribute 811 for the directory in which the target file system object 812 resides. 814 clientaddr4 816 struct clientaddr4 { 817 /* see struct rpcb in RFC 1833 */ 818 string r_netid<>; /* network id */ 819 string r_addr<>; /* universal address */ 820 }; 822 The clientaddr4 structure is used as part of the SETCLIENT 823 operation to specify the address of either the client that is 824 using a clientid or as part of the call back registration. 826 cb_client4 828 struct cb_client4 { 829 unsigned int cb_program; 830 clientaddr4 cb_location; 831 }; 833 This structure is used by the client to inform the server of its 835 Draft Specification NFS version 4 Protocol February 2000 837 call back address; includes the program number and client 838 address. 840 nfs_client_id4 842 struct nfs_client_id4 { 843 verifier4 verifier; 844 opaque id<>; 845 }; 847 This structure is part of the arguments to the SETCLIENTID 848 operation. 850 nfs_lockowner4 852 struct nfs_lockowner4 { 853 clientid4 clientid; 854 opaque owner<>; 855 }; 857 This structure is used to identify the owner of a OPEN share or 858 file lock. 860 Draft Specification NFS version 4 Protocol February 2000 862 3. RPC and Security Flavor 864 The NFS version 4 protocol is a Remote Procedure Call (RPC) 865 application that uses RPC version 2 and the corresponding eXternal 866 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 867 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 868 the mechanism to deliver stronger security for the NFS version 4 869 protocol. 871 3.1. Ports and Transports 873 Historically, NFS version 2 and version 3 servers have resided on 874 port 2049. The registered port 2049 [RFC1700] for the NFS protocol 875 should be the default configuration. Using the registered port for 876 NFS services means the NFS client will not need to use the RPC 877 binding protocols as described in [RFC1833]; this will allow NFS to 878 transit firewalls. 880 The transport used by the RPC service for the NFS version 4 protocol 881 MUST provide congestion control comparable to that defined for TCP in 882 [RFC2581]. If the operating environment implements TCP, the NFS 883 version 4 protocol SHOULD be supported over TCP. The NFS client and 884 server may use other transports if they support congestion control as 885 defined above and in those cases a mechanism may be provided to 886 override TCP usage in favor of another transport. 888 If TCP is used as the transport, the client and server SHOULD use 889 persistent connections. This will prevent the weakening of TCP's 890 congestion control via short lived connections. 892 3.2. Security Flavors 894 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 895 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 896 additional security flavor of RPCSEC_GSS has been introduced which 897 uses the functionality of GSS-API [RFC2078]. This allows for the use 898 of varying security mechanisms by the RPC layer without the 899 additional implementation overhead of adding RPC security flavors. 900 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 901 enable the mandatory security mechanism. Other flavors, such as, 902 AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well. 904 3.2.1. Security mechanisms for NFS version 4 906 The use of RPCSEC_GSS requires selection of: mechanism, quality of 907 protection, and service (authentication, integrity, privacy). The 908 remainder of this document will refer to these three parameters of 910 Draft Specification NFS version 4 Protocol February 2000 912 the RPCSEC_GSS security as the security triple. 914 3.2.1.1. Kerberos V5 as security triple 916 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 917 implemented and provide the following security triples. 919 column descriptions: 921 1 == number of pseudo flavor 922 2 == name of pseudo flavor 923 3 == mechanism's OID 924 4 == mechanism's algorithm(s) 925 5 == RPCSEC_GSS service 927 1 2 3 4 5 928 ----------------------------------------------------------------------- 929 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 930 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 931 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 932 for integrity, 933 and 56 bit DES 934 for privacy. 936 Note that the pseudo flavor is presented here as a mapping aid to the 937 implementor. Because this NFS protocol includes a method to 938 negotiate security and it understands the GSS-API mechanism, the 939 pseudo flavor is not needed. The pseudo flavor is needed for NFS 940 version 3 since the security negotiation is done via the MOUNT 941 protocol. 943 For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please 944 see [RFC2623]. 946 3.2.1.2. LIPKEY as a security triple 948 The LIPKEY GSS-API mechanism as described in [RFCXXXX] MUST be 949 implemented and provide the following security triples. The 950 definition of the columns matches the previous subsection "Kerberos 951 V5 as security triple" 953 1 2 3 4 5 954 ----------------------------------------------------------------------- 955 390006 lipkey TBD negotiated rpc_gss_svc_none 956 390007 lipkey-i TBD negotiated rpc_gss_svc_integrity 957 390008 lipkey-p TBD negotiated rpc_gss_svc_privacy 959 Draft Specification NFS version 4 Protocol February 2000 961 The mechanism algorithm is listed as "negotiated". This is because 962 LIPKEY is layered on SPKM-3 and in SPKM-3 [RFCXXXX] the 963 confidentiality and integrity algorithms are negotiated. Since 964 SPKM-3 specifies HMAC-MD5 for integrity as MANDATORY, 128 bit 965 cast5CBC for confidentiality for privacy as MANDATORY, and further 966 specifies that HMAC-MD5 and cast5CBC MUST be listed first before 967 weaker algorithms, specifying "negotiated" in column 4 does not 968 impair interoperability. In the event an SPKM-3 peer does not 969 support the mandatory algorithms, the other peer is free to accept or 970 reject the GSS-API context creation. 972 Because SPKM-3 negotiates the algorithms, subsequent calls to 973 LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality 974 of protection value of 0 (zero). See section 5.2 of [RFC2025] for an 975 explanation. 977 LIPKEY uses SPKM-3 to create a secure channel in which to pass a user 978 name and password from the client to the user. Once the user name 979 and password have been accepted by the server, calls to the LIPKEY 980 context are redirected to the SPKM-3 context. See [RFCXXXX] for more 981 details. 983 3.2.1.3. SPKM-3 as a security triple 985 The SPKM-3 GSS-API mechanism as described in [RFCXXXX] MUST be 986 implemented and provide the following security triples. The 987 definition of the columns matches the previous subsection "Kerberos 988 V5 as security triple". 990 1 2 3 4 5 991 ----------------------------------------------------------------------- 992 390009 spkm3 TBD negotiated rpc_gss_svc_none 993 390010 spkm3i TBD negotiated rpc_gss_svc_integrity 994 390011 spkm3p TBD negotiated rpc_gss_svc_privacy 996 For a discussion as to why the mechanism algorithm is listed as 997 "negotiated", see the previous section "LIPKEY as a security triple." 999 Because SPKM-3 negotiates the algorithms, subsequent calls to SPKM- 1000 3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality of 1001 protection value of 0 (zero). See section 5.2 of [RFC2025] for an 1002 explanation. 1004 Even though LIPKEY is layered onto SPKM-3, SPKM-3 is specified as a 1005 mandatory set of triples to handle the situation when the initiator 1006 (the client) is anonymous. If the initiator is anonymous, there will 1007 not be a user name and password to send to the target (the server). 1009 Draft Specification NFS version 4 Protocol February 2000 1011 3.3. Security Negotiation 1013 With the NFS version 4 server potentially offering multiple security 1014 mechanisms, the client needs a method to determine or negotiate which 1015 mechanism is to be used for its communication with the server. The 1016 NFS server may have multiple points within its file system name space 1017 that are available for use by NFS clients. In turn the NFS server 1018 may be configured such that each of these entry points may have 1019 different or multiple security mechanisms in use. 1021 The security negotiation between client and server must be done with 1022 a secure channel to eliminate the possibility of a third party 1023 intercepting the negotiation sequence and forcing the client and 1024 server to choose a lower level of security than required or desired. 1026 3.3.1. Security Error 1028 Based on the assumption that each NFS version 4 client and server 1029 must support a minimum set of security (i.e. LIPKEY, SPKM-3, and 1030 Kerberos-V5 all under RPCSEC_GSS), the NFS client will start its 1031 communication with the server with one of the minimal security 1032 triples. During communication with the server, the client may 1033 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 1034 server to notify the client that the security triple currently being 1035 used is not appropriate for access to the server's file system 1036 resources. The client is then responsible for determining what 1037 security triples are available at the server and choose one which is 1038 appropriate for the client. 1040 3.3.2. SECINFO 1042 The new SECINFO operation will allow the client to determine, on a 1043 per filehandle basis, what security triple is to be used for server 1044 access. In general, the client will not have to use the SECINFO 1045 procedure except during initial communication with the server or when 1046 the client crosses policy boundaries at the server. It is possible 1047 that the server's policies change during the client's interaction 1048 therefore forcing the client to negotiate a new security triple. 1050 3.4. Callback RPC Authentication 1052 The callback RPC (described later) must mutually authenticate the NFS 1053 server to the principal that acquired the delegation (also described 1054 later), using the same security flavor the original delegation 1055 operation used. 1057 Draft Specification NFS version 4 Protocol February 2000 1059 For AUTH_NONE, there are no principals, so this is a non-issue. 1061 For AUTH_SYS, the server simply uses the AUTH_SYS credential that the 1062 user used when it set up the delegation. 1064 For AUTH_DH, one commonly used convention is that the server uses the 1065 credentional corresponding to this AUTH_DH principal: 1067 unix.host@domain 1069 where host and domain are variables corresponding to the name of 1070 server host and directory services domain in which it lives such as a 1071 Network Information System domain or a DNS domain. 1073 Regardless of what security mechanism under RPCSEC_GSS is being used, 1074 the NFS server, MUST identify itself in GSS-API via a 1075 GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE 1076 names are of the form: 1078 service@hostname 1080 For NFS, the "service" element is 1082 nfs 1084 Implementations of security mechanisms will convert nfs@hostname to 1085 various different forms. For Kerberos V5 and LIPKEY, the following 1086 form is RECOMMENDED: 1088 nfs/hostname 1090 For Kerberos V5, nfs/hostname would be a server principal in the 1091 Kerberos Key Distribution Center database. For LIPKEY, this would be 1092 the username passed to the target (the NFS version 4 client that 1093 receives the callback). 1095 It should be noted that LIPKEY may not work for callbacks, since the 1096 LIPKEY client uses a user id/password. If the NFS client receiving 1097 the callback can authenticate the NFS server's user name/password 1098 pair, and if the user that the NFS server is authenticating to has a 1099 public key certificiate, then it works. 1101 Draft Specification NFS version 4 Protocol February 2000 1103 4. Filehandles 1105 The filehandle in the NFS protocol is a per server unique identifier 1106 for a file system object. The contents of the filehandle are opaque 1107 to the client. Therefore, the server is responsible for translating 1108 the filehandle to an internal representation of the file system 1109 object. Since the filehandle is the client's reference to an object 1110 and the client may cache this reference, the server should not reuse 1111 a filehandle for another file system object. If the server needs to 1112 reuse a filehandle value, the time elapsed before reuse SHOULD be 1113 large enough that it is likely the client no longer has a cached copy 1114 of the reused filehandle value. 1116 4.1. Obtaining the First Filehandle 1118 The operations of the NFS protocol are defined in terms of one or 1119 more filehandles. Therefore, the client needs a filehandle to 1120 initiate communication with the server. With the NFS version 2 1121 protocol [RFC1094] and the NFS version 3 protocol [RFC1813], there 1122 exists an ancillary protocol to obtain this first filehandle. The 1123 MOUNT protocol, RPC program number 100005, provides the mechanism of 1124 translating a string based file system path name to a filehandle 1125 which can then be used by the NFS protocols. 1127 The MOUNT protocol has deficiencies in the area of security and use 1128 via firewalls. This is one reason that the use of the public 1129 filehandle was introduced in [RFC2054] and [RFC2055]. With the use 1130 of the public filehandle in combination with the LOOKUP procedure in 1131 the NFS version 2 and 3 protocols, it has been demonstrated that the 1132 MOUNT protocol is unnecessary for viable interaction between NFS 1133 client and server. 1135 Therefore, the NFS version 4 protocol will not use an ancillary 1136 protocol for translation from string based path names to a 1137 filehandle. Two special filehandles will be used as starting points 1138 for the NFS client. 1140 4.1.1. Root Filehandle 1142 The first of the special filehandles is the ROOT filehandle. The 1143 ROOT filehandle is the "conceptual" root of the file system name 1144 space at the NFS server. The client uses or starts with the ROOT 1145 filehandle by employing the PUTROOTFH operation. The PUTROOTFH 1146 operation instructs the server to set the "current" filehandle to the 1147 ROOT of the server's file tree. Once this PUTROOTFH operation is 1148 used, the client can then traverse the entirety of the server's file 1150 Draft Specification NFS version 4 Protocol February 2000 1152 tree with the LOOKUP procedure. A complete discussion of the server 1153 name space is in the section "NFS Server Name Space". 1155 4.1.2. Public Filehandle 1157 The second special filehandle is the PUBLIC filehandle. Unlike the 1158 ROOT filehandle, the PUBLIC filehandle may be bound or represent an 1159 arbitrary file system object at the server. The server is 1160 responsible for this binding. It may be that the PUBLIC filehandle 1161 and the ROOT filehandle refer to the same file system object. 1162 However, it is up to the administrative software at the server and 1163 the policies of the server administrator to define the binding of the 1164 PUBLIC filehandle and server file system object. The client may not 1165 make any assumptions about this binding. 1167 4.2. Filehandle Types 1169 In the NFS version 2 and 3 protocols, there was one type of 1170 filehandle with a single set of semantics. The NFS version 4 1171 protocol introduces a new type of filehandle in an attempt to 1172 accommodate certain server environments. The first type of 1173 filehandle is 'persistent'. The semantics of a persistent filehandle 1174 are the same as the filehandles of the NFS version 2 and 3 protocols. 1175 The second or new type of filehandle is the "volatile" filehandle. 1177 The volatile filehandle type is being introduced to address server 1178 functionality or implementation issues which make correct 1179 implementation of a persistent filehandle infeasible. Some server 1180 environments do not provide a file system level invariant that can be 1181 used to construct a persistent filehandle. The underlying server 1182 file system may not provide the invariant or the server's file system 1183 programming interfaces may not provide access to the needed 1184 invariant. Volatile filehandles may ease the implementation of 1185 server functionality such as hierarchical storage management or file 1186 system reorganization or migration. However, the volatile filehandle 1187 increases the implementation burden for the client. However this 1188 increased burden is deemed acceptable based on the overall gains 1189 achieved by the protocol. 1191 Since the client will need to handle persistent and volatile 1192 filehandle differently, a file attribute is defined which may be used 1193 by the client to determine the filehandle types being returned by the 1194 server. 1196 Draft Specification NFS version 4 Protocol February 2000 1198 4.2.1. General Properties of a Filehandle 1200 The filehandle contains all the information the server needs to 1201 distinguish an individual file. To the client, the filehandle is 1202 opaque. The client stores filehandles for use in a later request and 1203 can compare two filehandles from the same server for equality by 1204 doing a byte-by-byte comparison. However, the client MUST NOT 1205 otherwise interpret the contents of filehandles. If two filehandles 1206 from the same server are equal, they MUST refer to the same file. If 1207 they are not equal, the client may use information provided by the 1208 server, in the form of file attributes, to determine whether they 1209 denote the same files or different files. The client would do this 1210 as necessary for client side caching. Servers SHOULD try to maintain 1211 a one-to-one correspondence between filehandles and files but this is 1212 not required. Clients MUST use filehandle comparisons only to 1213 improve performance, not for correct behavior. All clients need to 1214 be prepared for situations in which it cannot be determined whether 1215 two filehandles denote the same object and in such cases, avoid 1216 making invalid assumpions which might cause incorrect behavior. 1217 Further discussion of filehandle and attribute comparison in the 1218 context of data caching is presented in the section "Data Caching and 1219 File Identity". 1221 As an example, in the case that two different path names when 1222 traversed at the server terminate at the same file system object, the 1223 server SHOULD return the same filehandle for each path. This can 1224 occur if a hard link is used to create two file names which refer to 1225 the same underlying file object and associated data. For example, if 1226 paths /a/b/c and /a/d/c refer to the same file, the server SHOULD 1227 return the same filehandle for both path names traversals. 1229 4.2.2. Persistent Filehandle 1231 A persistent filehandle is defined as having a fixed value for the 1232 lifetime of the file system object to which it refers. Once the 1233 server creates the filehandle for a file system object, the server 1234 MUST accept the same filehandle for the object for the lifetime of 1235 the object. If the server restarts or reboots the NFS server must 1236 honor the same filehandle value as it did in the server's previous 1237 instantiation. Similarly, if the file system is migrated, the new 1238 NFS server must honor the same file handle as the old NFS server. 1240 The persistent filehandle will be become stale or invalid when the 1241 file system object is removed. When the server is presented with a 1242 persistent filehandle that refers to a deleted object, it MUST return 1243 an error of NFS4ERR_STALE. A filehandle may become stale when the 1244 file system containing the object is no longer available. The file 1246 Draft Specification NFS version 4 Protocol February 2000 1248 system may become unavailable if it exists on removable media and the 1249 media is no longer available at the server or the file system in 1250 whole has been destroyed or the file system has simply been removed 1251 from the server's name space (i.e. unmounted in a Unix environment). 1253 4.2.3. Volatile Filehandle 1255 A volatile filehandle does not share the same longevity 1256 characteristics of a persistent filehandle. The server may determine 1257 that a volatile filehandle is no longer valid at many different 1258 points in time. If the server can definitively determine that a 1259 volatile filehandle refers to an object that has been removed, the 1260 server should return NFS4ERR_STALE to the client (as is the case for 1261 persistent filehandles). In all other cases where the server 1262 determines that a volatile filehandle can no longer be used, it 1263 should return an error of NFS4ERR_FHEXPIRED. 1265 The mandatory attribute "fh_expire_type" is used by the client to 1266 determine what type of filehandle the server is providing for a 1267 particular file system. This attribute is a bitmask with the 1268 following values: 1270 FH4_PERSISTENT 1271 The value of FH4_PERSISTENT is used to indicate a persistent 1272 filehandle, which is valid until the object is removed from the 1273 file system. The server will not return NFS4ERR_FHEXPIRED for 1274 this filehandle. FH4_PERSISTENT is defined as a value in which 1275 none of the bits specified below are set. 1277 FH4_NOEXPIRE_WITH_OPEN 1278 The filehandle will not expire while client has the file open. 1279 If this bit is set, then the values FH4_VOLATILE_ANY or 1280 FH4_VOL_RENAME do not impact expiration while the file is open. 1281 Once the file is closed or if the FH4_NOEXPIRE_WITH_OPEN bit is 1282 false, the rest of the volatile related bits apply. 1284 FH4_VOLATILE_ANY 1285 The filehandle may expire at any time and will expire on during 1286 system migration. 1288 FH4_VOL_MIGRATION 1289 The filehandle will expire during file system migration and only 1290 then. May only be set if FH4_VOLATILE_ANY is not set. 1292 FH4_VOL_RENAME 1293 The filehandle may expire due to a rename. This includes a 1295 Draft Specification NFS version 4 Protocol February 2000 1297 rename by the requesting client or a rename by another client. 1298 May only be set if FH4_VOLATILE_ANY is not set. 1300 Servers which provide volatile filehandles should deny a RENAME or 1301 REMOVE that would effect an OPEN file or any of the components 1302 leading to the OPEN file. In addition, the server should deny all 1303 RENAME or REMOVE requests during the grace or lease period upon 1304 server restart. 1306 The reader may be wondering why there are three FH4_VOL* bits and why 1307 FH4_VOLATILE_ANY is exclusive of FH4_VOL_MIGRATION and 1308 FH4_VOL_RENAME. If the a filehandle is normally persistent but 1309 cannot persist across a file set migration, then the presence of the 1310 FH4_VOL_MIGRATION or FH4_VOL_RENAME tells the client that it can 1311 treat the file handle as persistent for purposes of maintaining a 1312 file name to file handle cache, except for the specific event 1313 described by the bit. However, FH4_VOLATILE_ANY tells the client 1314 that it should not maintain such a cache for unopened files. A 1315 server MUST not present FH4_VOLATILE_ANY with FH4_VOL_MIGRATION or 1316 FH4_VOL_RENAME as this will lead to confusion. FH4_VOLATILE_ANY 1317 implies that the file handle will expire upon migration or rename, in 1318 addition to other events. 1320 4.2.4. One Method of Constructing a Volatile Filehandle 1322 As mentioned, in some instances a filehandle is stale (no longer 1323 valid; perhaps because the file was removed from the server) or it is 1324 expired (the underlying file is valid but since the filehandle is 1325 volatile, it may have expired). Thus the server needs to be able to 1326 return NFS4ERR_STALE in the former case and NFS4ERR_FHEXPIRED in the 1327 latter case. This can be done by careful construction of the volatile 1328 filehandle. One possible implementation follows. 1330 A volatile filehandle, while opaque to the client could contain: 1332 [volatile bit = 1 | server boot time | slot | generation number] 1334 o slot is an index in the server volatile filehandle table 1336 o generation number is the generation number for the table 1337 entry/slot 1339 If the server boot time is less than the current server boot time, 1340 return NFS4ERR_FHEXPIRED. If slot is out of range, return 1341 NFS4ERR_BADHANDLE. If the generation number does not match, return 1343 Draft Specification NFS version 4 Protocol February 2000 1345 NFS4ERR_FHEXPIRED. 1347 When the server reboots, the table is gone (it is volatile). 1349 If volatile bit is 0, then it is a persistent filehandle with a 1350 different structure following it. 1352 4.3. Client Recovery from Filehandle Expiration 1354 If possible, the client SHOULD recover from the receipt of an 1355 NFS4ERR_FHEXPIRED error. The client must take on additional 1356 responsibility so that it may prepare itself to recover from the 1357 expiration of a volatile filehandle. If the server returns 1358 persistent filehandles, the client does not need these additional 1359 steps. 1361 For volatile filehandles, most commonly the client will need to store 1362 the component names leading up to and including the file system 1363 object in question. With these names, the client should be able to 1364 recover by finding a filehandle in the name space that is still 1365 available or by starting at the root of the server's file system name 1366 space. 1368 If the expired filehandle refers to an object that has been removed 1369 from the file system, obviously the client will not be able to 1370 recover from the expired filehandle. 1372 It is also possible that the expired filehandle refers to a file that 1373 has been renamed. If the file was renamed by another client, again 1374 it is possible that the original client will not be able to recover. 1375 However, in the case that the client itself is renaming the file and 1376 the file is open, it is possible that the client may be able to 1377 recover. The client can determine the new path name based on the 1378 processing of the rename request. The client can then regenerate the 1379 new filehandle based on the new path name. The client could also use 1380 the compound operation mechanism to construct a set of operations 1381 like: 1382 RENAME A B 1383 LOOKUP B 1384 GETFH 1386 Draft Specification NFS version 4 Protocol February 2000 1388 5. File Attributes 1390 To meet the requirements of extensibility and increased 1391 interoperability with non-Unix platforms, attributes must be handled 1392 in a flexible manner. The NFS Version 3 fattr3 structure contains a 1393 fixed list of attributes that not all clients and servers are able to 1394 support or care about. The fattr3 structure can not be extended as 1395 new needs arise and it provides no way to indicate non-support. With 1396 the NFS Version 4 protocol, the client will be able to ask what 1397 attributes the server supports and will be able to request only those 1398 attributes in which it is interested. 1400 To this end, attributes will be divided into three groups: mandatory, 1401 recommended, and named. Both mandatory and recommended attributes 1402 are supported in the NFS version 4 protocol by a specific and well- 1403 defined encoding and are identified by number. They are requested by 1404 setting a bit in the bit vector sent in the GETATTR request; the 1405 server response includes a bit vector to list what attributes were 1406 returned in the response. New mandatory or recommended attributes 1407 may be added to the NFS protocol between major revisions by 1408 publishing a standards-track RFC which allocates a new attribute 1409 number value and defines the encoding for the attribute. See the 1410 section "Minor Versioning" for further discussion. 1412 Named attributes are accessed by the new OPENATTR operation, which 1413 accesses a hidden directory of attributes associated with a file 1414 system object. OPENATTR takes a filehandle for the object and 1415 returns the filehandle for the attribute hierarchy. The filehandle 1416 for the named attributes is a directory object accessible by LOOKUP 1417 or READDIR and contains files whose names represent the named 1418 attributes and whose data bytes are the value of the attribute. For 1419 example: 1421 LOOKUP "foo" ; look up file 1422 GETATTR attrbits 1423 OPENATTR ; access foo's named attributes 1424 LOOKUP "x11icon" ; look up specific attribute 1425 READ 0,4096 ; read stream of bytes 1427 Named attributes are intended for data needed by applications rather 1428 than by an NFS client implementation. NFS implementors are strongly 1429 encouraged to define their new attributes as recommended attributes 1430 by bringing them to the IETF standards-track process. 1432 The set of attributes which are classified as mandatory is 1433 deliberately small since servers must do whatever it takes to support 1435 Draft Specification NFS version 4 Protocol February 2000 1437 them. The recommended attributes may be unsupported; though a server 1438 should support as many as it can. Attributes are deemed mandatory if 1439 the data is both needed by a large number of clients and is not 1440 otherwise reasonably computable by the client when support is not 1441 provided on the server. 1443 5.1. Mandatory Attributes 1445 These MUST be supported by every NFS Version 4 client and server in 1446 order to ensure a minimum level of interoperability. The server must 1447 store and return these attributes and the client must be able to 1448 function with an attribute set limited to these attributes. With 1449 just the mandatory attributes some client functionality may be 1450 impaired or limited in some ways. A client may ask for any of these 1451 attributes to be returned by setting a bit in the GETATTR request and 1452 the server must return their value. 1454 5.2. Recommended Attributes 1456 These attributes are understood well enough to warrant support in the 1457 NFS Version 4 protocol. However, they may not be supported on all 1458 clients and servers. A client may ask for any of these attributes to 1459 be returned by setting a bit in the GETATTR request but must handle 1460 the case where the server does not return them. A client may ask for 1461 the set of attributes the server supports and should not request 1462 attributes the server does not support. A server should be tolerant 1463 of requests for unsupported attributes and simply not return them 1464 rather than considering the request an error. It is expected that 1465 servers will support all attributes they comfortably can and only 1466 fail to support attributes which are difficult to support in their 1467 operating environments. A server should provide attributes whenever 1468 they don't have to "tell lies" to the client. For example, a file 1469 modification time should be either an accurate time or should not be 1470 supported by the server. This will not always be comfortable to 1471 clients but it seems that the client has a better ability to 1472 fabricate or construct an attribute or do without the attribute. 1474 5.3. Named Attributes 1476 These attributes are not supported by direct encoding in the NFS 1477 Version 4 protocol but are accessed by string names rather than 1478 numbers and correspond to an uninterpreted stream of bytes which are 1479 stored with the file system object. The name space for these 1480 attributes may be accessed by using the OPENATTR operation. The 1481 OPENATTR operation returns a filehandle for a virtual "attribute 1483 Draft Specification NFS version 4 Protocol February 2000 1485 directory" and further perusal of the name space may be done using 1486 READDIR and LOOKUP operations on this filehandle. Named attributes 1487 may then be examined or changed by normal READ and WRITE and CREATE 1488 operations on the filehandles returned from READDIR and LOOKUP. 1489 Named attributes may have attributes. 1491 It is recommended that servers support arbitrary named attributes. A 1492 client should not depend on the ability to store any named attributes 1493 in the server's file system. If a server does support named 1494 attributes, a client which is also able to handle them should be able 1495 to copy a file's data and meta-data with complete transparency from 1496 one location to another; this would imply that names allowed for 1497 regular directory entries are valid for named attribute names as 1498 well. 1500 Names of attributes will not be controlled by this document or other 1501 IETF standards track documents. See the section "IANA 1502 Considerations" for further discussion. 1504 Draft Specification NFS version 4 Protocol February 2000 1506 5.4. Mandatory Attributes - Definitions 1508 Name # DataType Access Description 1509 ___________________________________________________________________ 1510 supp_attr 0 bitmap READ The bit vector which 1511 would retrieve all 1512 mandatory and 1513 recommended attributes 1514 that are supported for 1515 this object. 1517 object_type 1 nfs4_ftype READ The type of the object 1518 (file, directory, 1519 symlink) 1521 fh_expire_type 2 uint32 READ Server uses this to 1522 specify filehandle 1523 expiration behavior to 1524 the client. See the 1525 section "Filehandles" 1526 for additional 1527 description. 1529 change 3 uint64 READ A value created by the 1530 server that the client 1531 can use to determine 1532 if file data, 1533 directory contents or 1534 attributes of the 1535 object have been 1536 modified. The server 1537 may return the 1538 object's time_modify 1539 attribute for this 1540 attribute's value but 1541 only if the file 1542 system object can not 1543 be updated more 1544 frequently than the 1545 resolution of 1546 time_modify. 1548 object_size 4 uint64 R/W The size of the object 1549 in bytes. 1551 Draft Specification NFS version 4 Protocol February 2000 1553 link_support 5 boolean READ Does the object's file 1554 system supports hard 1555 links? 1557 symlink_support 6 boolean READ Does the object's file 1558 system supports 1559 symbolic links? 1561 named_attr 7 boolean READ Does this object have 1562 named attributes? 1564 fsid 8 fsid4 READ Unique file system 1565 identifier for the 1566 file system holding 1567 this object. fsid 1568 contains major and 1569 minor components each 1570 of which are uint64. 1572 unique_handles 9 boolean READ Are two distinct 1573 filehandles guaranteed 1574 to refer to two 1575 different file system 1576 objects? 1578 lease_time 10 nfs_lease4 READ Duration of leases at 1579 server in seconds. 1581 rdattr_error 11 enum READ Error returned from 1582 getattr during 1583 readdir. 1585 Draft Specification NFS version 4 Protocol February 2000 1587 5.5. Recommended Attributes - Definitions 1589 Name # Data Type Access Description 1590 _____________________________________________________________________ 1591 ACL 12 nfsace4<> R/W The access control 1592 list for the object. 1594 aclsupport 13 uint32 READ Indicates what types 1595 of ACLs are supported 1596 on the current file 1597 system. 1599 archive 14 boolean R/W Whether or not this 1600 file has been 1601 archived since the 1602 time of last 1603 modification 1604 (deprecated in favor 1605 of backup_time). 1607 cansettime 15 boolean READ Whether or not this 1608 object's file system 1609 can fill in the times 1610 on a SETATTR request 1611 without an explicit 1612 time. 1614 case_insensitive 16 boolean READ Are filename 1615 comparisons on this 1616 file system case 1617 insensitive? 1619 case_preserving 17 boolean READ Is filename case on 1620 this file system 1621 preserved? 1623 Draft Specification NFS version 4 Protocol February 2000 1625 chown_restricted 18 boolean READ If TRUE, the server 1626 will reject any 1627 request to change 1628 either the owner or 1629 the group associated 1630 with a file if the 1631 caller is not a 1632 privileged user (for 1633 example, "root" in 1634 Unix operating 1635 environments or in NT 1636 the "Take Ownership" 1637 privilege) 1639 filehandle 19 nfs4_fh READ The filehandle of 1640 this object 1641 (primarily for 1642 readdir requests). 1644 fileid 20 uint64 READ A number uniquely 1645 identifying the file 1646 within the file 1647 system. 1649 files_avail 21 uint64 READ File slots available 1650 to this user on the 1651 file system 1652 containing this 1653 object - this should 1654 be the smallest 1655 relevant limit. 1657 files_free 22 uint64 READ Free file slots on 1658 the file system 1659 containing this 1660 object - this should 1661 be the smallest 1662 relevant limit. 1664 files_total 23 uint64 READ Total file slots on 1665 the file system 1666 containing this 1667 object. 1669 Draft Specification NFS version 4 Protocol February 2000 1671 fs_locations 24 fs_locations READ Locations where this 1672 file system may be 1673 found. If the server 1674 returns NFS4ERR_MOVED 1675 as an error, this 1676 attribute must be 1677 supported. 1679 hidden 25 boolean R/W Is file considered 1680 hidden with respect 1681 to the WIN32 API? 1683 homogeneous 26 boolean READ Whether or not this 1684 object's file system 1685 is homogeneous, i.e. 1686 whether pathconf is 1687 the same for all file 1688 system objects. 1690 maxfilesize 27 uint64 READ Maximum supported 1691 file size for the 1692 file system of this 1693 object. 1695 maxlink 28 uint32 READ Maximum number of 1696 links for this 1697 object. 1699 maxname 29 uint32 READ Maximum filename size 1700 supported for this 1701 object. 1703 maxread 30 uint64 READ Maximum read size 1704 supported for this 1705 object. 1707 Draft Specification NFS version 4 Protocol February 2000 1709 maxwrite 31 uint64 READ Maximum write size 1710 supported for this 1711 object. This 1712 attribute SHOULD be 1713 supported if the file 1714 is writable. Lack of 1715 this attribute can 1716 lead to the client 1717 either wasting 1718 bandwidth or not 1719 receiving the best 1720 performance. 1722 mime_type 32 utf8<> R/W MIME body 1723 type/subtype of this 1724 object. 1726 mode 33 mode4 R/W Unix-style permission 1727 bits for this object 1728 (deprecated in favor 1729 of ACLs) 1731 no_trunc 34 boolean READ If a name longer than 1732 name_max is used, 1733 will an error be 1734 returned or will the 1735 name be truncated? 1737 numlinks 35 uint32 READ Number of links to 1738 this object. 1740 owner 36 utf8<> R/W The string name of 1741 the owner of this 1742 object. 1744 owner_group 37 utf8<> R/W The string name of 1745 the group of the 1746 owner of this object. 1748 quota_hard 38 uint64 READ For definition see 1749 "Quota Attributes" 1750 section below. 1752 quota_soft 39 uint64 READ For definition see 1753 "Quota Attributes" 1754 section below. 1756 Draft Specification NFS version 4 Protocol February 2000 1758 quota_used 40 uint64 READ For definition see 1759 "Quota Attributes" 1760 section below. 1762 rawdev 41 specdata4 READ Raw device 1763 identifier. 1765 space_avail 42 uint64 READ Disk space in bytes 1766 available to this 1767 user on the file 1768 system containing 1769 this object - this 1770 should be the 1771 smallest relevant 1772 limit. 1774 space_free 43 uint64 READ Free disk space in 1775 bytes on the file 1776 system containing 1777 this object - this 1778 should be the 1779 smallest relevant 1780 limit. 1782 space_total 44 uint64 READ Total disk space in 1783 bytes on the file 1784 system containing 1785 this object. 1787 space_used 45 uint64 READ Number of file system 1788 bytes allocated to 1789 this object. 1791 system 46 boolean R/W Is this file is a 1792 system file with 1793 respect to the WIN32 1794 API? 1796 time_access 47 nfstime4 READ The time of last 1797 access to the object. 1799 time_access_set 48 settime4 WRITE Set the time of last 1800 access to the object. 1801 SETATTR use only. 1803 time_backup 49 nfstime4 R/W The time of last 1804 backup of the object. 1806 Draft Specification NFS version 4 Protocol February 2000 1808 time_create 50 nfstime4 R/W The time of creation 1809 of the object. This 1810 attribute does not 1811 have any relation to 1812 the traditional Unix 1813 file attribute 1814 "ctime" or "change 1815 time". 1817 time_delta 51 nfstime4 READ Smallest useful 1818 server time 1819 granularity. 1821 time_metadata 52 nfstime4 R/W The time of last 1822 meta-data 1823 modification of the 1824 object. 1826 time_modify 53 nfstime4 READ The time of last 1827 modification to the 1828 object. 1830 time_modify_set 54 settime4 WRITE Set the time of last 1831 modification to the 1832 object. SETATTR use 1833 only. 1835 5.6. Interpreting owner and owner_group 1837 The recommended attributes "owner" and "owner_group" are represented 1838 in terms of a UTF-8 string. To avoid a representation that is tied 1839 to a particular underlying implementation at the client or server, 1840 the use of the UTF-8 string has been chosen. Note that section 6.1 1841 of [RFC2624] provides additional rationale. It is expected that the 1842 client and server will have their own local representation of owner 1843 and owner_group that is used for local storage or presentation to the 1844 end user. Therefore, it is expected that when these attributes are 1845 transferred between the client and server that the local 1846 representation is translated to a syntax of the form 1847 "user@dns_domain". This will allow for a client and server that do 1848 not use the same local representation the ability to translate to a 1849 common syntax that can be interpreted by both. 1851 The translation is not specified as part of the protocol. This 1852 allows various solutions to be employed. For example, a local 1854 Draft Specification NFS version 4 Protocol February 2000 1856 translation table may be consulted that maps between a numeric id to 1857 the user@dns_domain syntax. A name service may also be used to 1858 accomplish the translation. The "dns_domain" portion of the owner 1859 string is meant to be a DNS domain name. For example, user@ietf.org. 1861 In the case where there is no translation available to the client or 1862 server, the attribute value must be constructed without the "@". 1863 Therefore, the absence of the @ from the owner or owner_group 1864 attribute signifies that no translation was available and the 1865 receiver of the attribute should not place any special meaning with 1866 the attribute value. Even though the attribute value can not be 1867 translated, it may still be useful. In the case of a client, the 1868 attribute string may be used for local display of ownership. 1870 5.7. Quota Attributes 1872 For the attributes related to file system quotas, the following 1873 definitions apply: 1875 quota_avail_soft 1876 The value in bytes which represents the amount of additional 1877 disk space that can be allocated to this file or directory 1878 before the user may reasonably be warned. It is understood that 1879 this space may be consumed by allocations to other files or 1880 directories though there is a rule as to which other files or 1881 directories. 1883 quota_avail_hard 1884 The value in bytes which represent the amount of additional disk 1885 space beyond the current allocation that can be allocated to 1886 this file or directory before further allocations will be 1887 declined. It is understood that this space may be consumed by 1888 allocations to other files or directories. 1890 quota_used 1891 The value in bytes which represent the amount of disc space used 1892 by this file or directory and possibly a number of other similar 1893 files or directories, where the set of "similar" meets at least 1894 the criterion that allocating space to any file or directory in 1895 the set will reduce the "quota_avail_hard" of every other file 1896 or directory in the set. 1898 Note that there may be a number of distinct but overlapping sets 1899 of files or directories for which a quota_used value is 1900 maintained. E.g. "all files with a given owner", "all files with 1902 Draft Specification NFS version 4 Protocol February 2000 1904 a given group owner". etc. 1906 The server is at liberty to choose any of those sets but should 1907 do so in a repeatable way. The rule may be configured per- 1908 filesystem or may be "choose the set with the smallest quota". 1910 5.8. Access Control Lists 1912 The NFS ACL attribute is an array of access control entries (ACE). 1913 There are various access control entry types. The server is able to 1914 communicate which ACE types are supported by returning the 1915 appropriate value within the aclsupport attribute. The types of ACEs 1916 are defined as follows: 1918 Type Description 1919 _____________________________________________________ 1920 ALLOW Explicitly grants the access defined in 1921 acemask4 to the file or directory. 1923 DENY Explicitly denies the access defined in 1924 acemask4 to the file or directory. 1926 AUDIT LOG (system dependant) any access 1927 attempt to a file or directory which 1928 uses any of the access methods specified 1929 in acemask4. 1931 ALARM Generate a system ALARM (system 1932 dependant) when any access attempt is 1933 made to a file or directory for the 1934 access methods specified in acemask4. 1936 The NFS ACE attribute is defined as follows: 1938 typedef uint32_t acetype4; 1939 typedef uint32_t aceflag4; 1940 typedef uint32_t acemask4; 1942 struct nfsace4 { 1943 acetype4 type; 1944 aceflag4 flag; 1945 acemask4 access_mask; 1946 utf8string who; 1947 }; 1949 To determine if an ACCESS or OPEN request succeeds each nfsace4 entry 1950 is processed in order by the server. Only ACEs which have a "who" 1952 Draft Specification NFS version 4 Protocol February 2000 1954 that matches the requester are considered. Each ACE is processed 1955 until all of the bits of the requester's access have been ALLOWED. 1956 Once a bit (see below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it 1957 is no longer considered in the processing of later ACEs. If an 1958 ACCESS_DENIED_ACE is encountered where the requester's mode still has 1959 unALLOWED bits in common with the "access_mask" of the ACE, the 1960 request is denied. 1962 The bitmask constants used to represent the above definitions within 1963 the aclsupport attribute are as follows: 1965 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 1966 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 1967 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 1968 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 1970 5.8.1. ACE type 1972 The semantics of the "type" field follow the descriptions provided 1973 above. 1975 The bitmask constants used to for the type field are as follows: 1977 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 1978 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 1979 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 1980 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 1982 5.8.2. ACE flag 1984 The "flag" field contains values based on the following descriptions. 1986 ACE4_FILE_INHERIT_ACE 1988 Can be placed on a directory and indicates that this ACE should be 1989 added to each new non-directory file created. 1991 ACE4_DIRECTORY_INHERIT_ACE 1993 Can be placed on a directory and indicates that this ACE should be 1994 added to each new directory created. 1996 ACE4_INHERIT_ONLY_ACE 1998 Draft Specification NFS version 4 Protocol February 2000 2000 Can be placed on a directory but does not apply to the directory, 2001 only to newly created files/directories as specified by the above two 2002 flags. 2004 ACE4_NO_PROPAGATE_INHERIT_ACE 2006 Can be placed on a directory. Normally when a new directory is 2007 created and an ACE exists on the parent directory which is marked 2008 ACL4_DIRECTORY_INHERIT_ACE, two ACEs are placed on the new directory. 2009 One for the directory itself and one which is an inheritable ACE for 2010 newly created directories. This flag tells the server to not place 2011 an ACE on the newly created directory which is inheritable by 2012 subdirectories of the created directory. 2014 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 2016 ACL4_FAILED_ACCESS_ACE_FLAG 2018 Both indicate for AUDIT and ALARM which state to log the event. On 2019 every ACCESS or OPEN call which occurs on a file or directory which 2020 has an ACL that is of type ACE4_SYSTEM_AUDIT_ACE_TYPE or 2021 ACE4_SYSTEM_ALARM_ACE_TYPE, the attempted access is compared to the 2022 ace4mask of these ACLs. If the access is a subset of ace4mask and the 2023 identifier match, an AUDIT trail or an ALARM is generated. By 2024 default this happens regardless of the success or failure of the 2025 ACCESS or OPEN call. 2027 The flag ACE4_SUCCESSFUL_ACCESS_ACE_FLAG only produces the AUDIT or 2028 ALARM if the ACCESS or OPEN call is successful. The 2029 ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS 2030 or OPEN call fails. 2032 ACE4_IDENTIFIER_GROUP 2034 Indicates that the "who" refers to a GROUP as defined under Unix. 2036 The bitmask constants used to for the flag field are as follows: 2038 const ACE4_FILE_INHERIT_ACE = 0x00000001; 2039 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 2040 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 2041 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 2042 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 2044 Draft Specification NFS version 4 Protocol February 2000 2046 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 2047 const ACE4_IDENTIFIER_GROUP = 0x00000040; 2049 5.8.3. ACE Access Mask 2051 The access_mask field contains values based on the following: 2053 Access Description 2054 _______________________________________________________________ 2055 READ_DATA Permission to read the data of the file 2056 LIST_DIRECTORY Permission to list the contents of a 2057 directory 2058 WRITE_DATA Permission to modify the file's data 2059 ADD_FILE Permission to add a new file to a 2060 directory 2061 APPEND_DATA Permission to append data to a file 2062 ADD_SUBDIRECTORY Permission to create a subdirectory to a 2063 directory 2064 READ_NAMED_ATTRS Permission to read the named attributes 2065 of a file 2066 WRITE_NAMED_ATTRS Permission to write the named attributes 2067 of a file 2068 EXECUTE Permission to execute a file 2069 DELETE_CHILD Permission to delete a file or directory 2070 within a directory 2071 READ_ATTRIBUTES The ability to read basic attributes 2072 (non-acls) of a file 2073 WRITE_ATTRIBUTES Permission to change basic attributes 2074 (non-acls) of a file 2076 DELETE Permission to Delete the File 2077 READ_ACL Permission to Read the ACL 2078 WRITE_ACL Permission to Write the ACL 2079 WRITE_OWNER Permission to change the owner 2080 SYNCHRONIZE Permission to access file locally at the 2081 server with synchronous reads and writes 2083 The bitmask constants used to for the access mask field are as 2084 follows: 2086 const ACE4_READ_DATA = 0x00000001; 2087 const ACE4_LIST_DIRECTORY = 0x00000001; 2088 const ACE4_WRITE_DATA = 0x00000002; 2089 const ACE4_ADD_FILE = 0x00000002; 2090 const ACE4_APPEND_DATA = 0x00000004; 2091 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 2093 Draft Specification NFS version 4 Protocol February 2000 2095 const ACE4_READ_NAMED_ATTRS = 0x00000008; 2096 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 2097 const ACE4_EXECUTE = 0x00000020; 2098 const ACE4_DELETE_CHILD = 0x00000040; 2099 const ACE4_READ_ATTRIBUTES = 0x00000080; 2100 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 2102 const ACE4_DELETE = 0x00010000; 2103 const ACE4_READ_ACL = 0x00020000; 2104 const ACE4_WRITE_ACL = 0x00040000; 2105 const ACE4_WRITE_OWNER = 0x00080000; 2106 const ACE4_SYNCHRONIZE = 0x00100000; 2108 5.8.4. ACE who 2110 There are several special identifiers ("who") which need to be 2111 understood universally. Some of these identifiers cannot be 2112 understood when an NFS client accesses the server, but have meaning 2113 when a local process accesses the file. The ability to display and 2114 modify these permissions is permitted over NFS. 2116 Who Description 2117 _______________________________________________________________ 2118 "OWNER" The owner of the file. 2119 "GROUP" The group associated with the file. 2120 "EVERYONE" The world. 2121 "INTERACTIVE" Accessed from an interactive terminal. 2122 "NETWORK" Accessed via the network. 2123 "DIALUP" Accessed as a dialup user to the server. 2124 "BATCH" Accessed from a batch job. 2125 "ANONYMOUS" Accessed without any authentication. 2126 "AUTHENTICATED" Any authenticated user (opposite of 2127 ANONYMOUS) 2128 "SERVICE" Access from a system service. 2130 To avoid conflict, these special identitifers are distinguish by an 2131 appended "@" and should appear in the form "xxxx@" (note: no domain 2132 name after the "@"). For example: ANONYMOUS@. 2134 Draft Specification NFS version 4 Protocol February 2000 2136 6. File System Migration and Replication 2138 With the use of the recommended attribute "fs_locations", the NFS 2139 version 4 server has a method of providing file system migration or 2140 replication services. For the purposes of migration and replication, 2141 a file system will be defined as all files that share a given fsid 2142 (both major and minor values are the same). 2144 The fs_locations attribute provides a list of file system locations. 2145 These locations are specified by providing the server name (either 2146 DNS domain or IP address) and the path name representing the root of 2147 the file system. Depending on the type of service being provided, 2148 the list will provide a new location or a set of alternate locations 2149 for the file system. The client will use this information to 2150 redirect its requests to the new server. 2152 6.1. Replication 2154 It is expected that file system replication will be used in the case 2155 of read-only data. Typically, the file system will be replicated on 2156 two or more servers. The fs_locations attribute will provide the 2157 list of these locations to the client. On first access of the file 2158 system, the client should obtain the value of the fs_locations 2159 attribute. If, in the future, the client finds the server 2160 unresponsive, the client may attempt to use another server specified 2161 by fs_locations. 2163 If applicable, the client must take the appropriate steps to recover 2164 valid filehandles from the new server. This is described in more 2165 detail in the following sections. 2167 6.2. Migration 2169 File system migration is used to move a file system from one server 2170 to another. Migration is typically used for a file system that is 2171 writable and has a single copy. The expected use of migration is for 2172 load balancing or general resource reallocation. The protocol does 2173 not specify how the file system will be moved between servers. This 2174 server-to-server transfer mechanism is left to the server 2175 implementor. However, the method used to communicate the migration 2176 event between client and server is specified here. 2178 Once the servers participating in the migration have completed the 2179 move of the file system, the error NFS4ERR_MOVED will be returned for 2180 subsequent requests received by the original server. The 2181 NFS4ERR_MOVED error is returned for all operations except GETATTR. 2183 Draft Specification NFS version 4 Protocol February 2000 2185 Upon receiving the NFS4ERR_MOVED error, the client will obtain the 2186 value of the fs_locations attribute. The client will then use the 2187 contents of the attribute to redirect its requests to the specified 2188 server. To facilitate the use of GETATTR, operations such as PUTFH 2189 must also be accepted by the server for the migrated file system's 2190 filehandles. Note that if the server returns NFS4ERR_MOVED, the 2191 server MUST support the fs_locations attribute. 2193 If the client requests more attributes than fs_locations, the server 2194 may return fs_locations only. This is to be expected since the 2195 server has migrated the file system and may not have a method of 2196 obtaining additional attribute data. 2198 The server implementor needs to be careful in developing a migration 2199 solution. The server must consider all of the state information 2200 clients may have outstanding at the server. This includes but is not 2201 limited to locking/share state, delegation state, and asynchronous 2202 file writes which are represented by WRITE and COMMIT verifiers. The 2203 server should strive to minimize the impact on its clients during and 2204 after the migration process. 2206 6.3. Interpretation of the fs_locations Attribute 2208 The fs_location attribute is structured in the following way: 2210 struct fs_location { 2211 utf8string server<>; 2212 pathname4 rootpath; 2213 }; 2215 struct fs_locations { 2216 pathname4 fs_root; 2217 fs_location locations<>; 2218 }; 2220 The fs_location struct is used to represent the location of a file 2221 system by providing a server name and the path to the root of the 2222 file system. For a multi-homed server or a set of servers that use 2223 the same rootpath, an array of server names may be provided. An 2224 entry in the server array is an UTF8 string and represents one of a 2225 traditional DNS host name, IPv4 address, or IPv6 address. It is not 2226 a requirement that all servers that share the same rootpath be listed 2227 in one fs_location struct. The array of server names is provided for 2228 convenience. Servers that share the same rootpath may also be listed 2229 in separate fs_location entries in the fs_locations attribute. 2231 The fs_locations struct and attribute then contains an array of 2233 Draft Specification NFS version 4 Protocol February 2000 2235 locations. Since the name space of each server may be constructed 2236 differently, the "fs_root" field is provided. The path represented 2237 by fs_root represents the location of the file system in the server's 2238 name space. Therefore, the fs_root path is only associated with the 2239 server from which the fs_locations attribute was obtained. The 2240 fs_root path is meant to aid the client in locating the file system 2241 at the various servers listed. 2243 As an example, there is a replicated file system located at two 2244 servers (servA and servB). At servA the file system is located at 2245 path "/a/b/c". At servB the file system is located at path "/x/y/z". 2246 In this example the client accesses the file system first at servA 2247 with a multi-component lookup path of "/a/b/c/d". Since the client 2248 used a multi-component lookup to obtain the filehandle at "/a/b/c/d", 2249 it is unaware that the file system's root is located in servA's name 2250 space at "/a/b/c". When the client switches to servB, it will need 2251 to determine that the directory it first referenced at servA is now 2252 represented by the path "/x/y/z/d" on servB. To facilitate this, the 2253 fs_locations attribute provided by servA would have a fs_root value 2254 of "/a/b/c" and two entries in fs_location. One entry in fs_location 2255 will be for itself (servA) and the other will be for servB with a 2256 path of "/x/y/z". With this information, the client is able to 2257 substitute "/x/y/z" for the "/a/b/c" at the beginning of its access 2258 path and construct "/x/y/z/d" to use for the new server. 2260 6.4. Filehandle Recovery for Migration or Replication 2262 Filehandles for file systems that are replicated or migrated 2263 generally have the same semantics as for file systems that are not 2264 replicated or migrated. For example, if a file system has persistent 2265 filehandles and it is migrated to another server, the filehandle 2266 values for the file system will be valid at the new server. 2268 For volatile filehandles, the servers involved likely do not have a 2269 mechanism to transfer filehandle format and content between 2270 themselves. Therefore, a server may have difficulty in determining 2271 if a volatile filehandle from an old server should return an error of 2272 NFS4ERR_FHEXPIRED. Therefore, the client is informed, with the use 2273 of the fh_expire_type attribute, whether volatile filehandles will 2274 expire at the migration or replication event. If the bit 2275 FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client 2276 must treat the volatile filehandle as if the server had returned the 2277 NFS4ERR_FHEXPIRED error. At the migration or replication event in 2278 the presence of the FH4_VOL_MIGRATION bit, the client will not 2279 present the original or old volatile file handle to the new server. 2280 The client will start its communication with the new server by 2281 recovering its filehandles using the saved file names. 2283 Draft Specification NFS version 4 Protocol February 2000 2285 7. NFS Server Name Space 2287 7.1. Server Exports 2289 On a UNIX server the name space describes all the files reachable by 2290 pathnames under the root directory or "/". On a Windows NT server 2291 the name space constitutes all the files on disks named by mapped 2292 disk letters. NFS server administrators rarely make the entire 2293 server's file system name space available to NFS clients. More often 2294 portions of the name space are made available via an "export" 2295 feature. In previous versions of the NFS protocol, the root 2296 filehandle for each export is obtained through the MOUNT protocol; 2297 the client sends a string that identifies the export of name space 2298 and the server returns the root filehandle for it. The MOUNT 2299 protocol supports an EXPORTS procedure that will enumerate the 2300 server's exports. 2302 7.2. Browsing Exports 2304 The NFS version 4 protocol provides a root filehandle that clients 2305 can use to obtain filehandles for these exports via a multi-component 2306 LOOKUP. A common user experience is to use a graphical user 2307 interface (perhaps a file "Open" dialog window) to find a file via 2308 progressive browsing through a directory tree. The client must be 2309 able to move from one export to another export via single-component, 2310 progressive LOOKUP operations. 2312 This style of browsing is not well supported by the NFS version 2 and 2313 3 protocols. The client expects all LOOKUP operations to remain 2314 within a single server file system. For example, the device 2315 attribute will not change. This prevents a client from taking name 2316 space paths that span exports. 2318 An automounter on the client can obtain a snapshot of the server's 2319 name space using the EXPORTS procedure of the MOUNT protocol. If it 2320 understands the server's pathname syntax, it can create an image of 2321 the server's name space on the client. The parts of the name space 2322 that are not exported by the server are filled in with a "pseudo file 2323 system" that allows the user to browse from one mounted file system 2324 to another. There is a drawback to this representation of the 2325 server's name space on the client: it is static. If the server 2326 administrator adds a new export the client will be unaware of it. 2328 Draft Specification NFS version 4 Protocol February 2000 2330 7.3. Server Pseudo File System 2332 NFS version 4 servers avoid this name space inconsistency by 2333 presenting all the exports within the framework of a single server 2334 name space. An NFS version 4 client uses LOOKUP and READDIR 2335 operations to browse seamlessly from one export to another. Portions 2336 of the server name space that are not exported are bridged via a 2337 "pseudo file system" that provides a view of exported directories 2338 only. A pseudo file system has a unique fsid and behaves like a 2339 normal, read only file system. 2341 Based on the construction of the server's name space, it is possible 2342 that multiple pseudo file systems may exist. For example, 2344 /a pseudo file system 2345 /a/b real file system 2346 /a/b/c pseudo file system 2347 /a/b/c/d real file system 2349 Each of the pseudo file systems are consider separate entities and 2350 therefore will have a unique fsid. 2352 7.4. Multiple Roots 2354 The DOS and Windows operating environments are sometimes described as 2355 having "multiple roots". File systems are commonly represented as 2356 disk letters. MacOS represents file systems as top level names. NFS 2357 version 4 servers for these platforms can construct a pseudo file 2358 system above these root names so that disk letters or volume names 2359 are simply directory names in the pseudo root. 2361 7.5. Filehandle Volatility 2363 The nature of the server's pseudo file system is that it is a logical 2364 representation of file system(s) available from the server. 2365 Therefore, the pseudo file system is most likely constructed 2366 dynamically when the server is first instantiated. It is expected 2367 that the pseudo file system may not have an on disk counterpart from 2368 which persistent filehandles could be constructed. Even though it is 2369 preferable that the server provide persistent filehandles for the 2370 pseudo file system, the NFS client should expect that pseudo file 2371 system filehandles are volatile. This can be confirmed by checking 2372 the associated "fh_expire_type" attribute for those filehandles in 2373 question. If the filehandles are volatile, the NFS client must be 2374 prepared to recover a filehandle value (e.g. with a multi-component 2375 LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 2377 Draft Specification NFS version 4 Protocol February 2000 2379 7.6. Exported Root 2381 If the server's root file system is exported, one might conclude that 2382 a pseudo-file system is not needed. This would be wrong. Assume the 2383 following file systems on a server: 2385 / disk1 (exported) 2386 /a disk2 (not exported) 2387 /a/b disk3 (exported) 2389 Because disk2 is not exported, disk3 cannot be reached with simple 2390 LOOKUPs. The server must bridge the gap with a pseudo-file system. 2392 7.7. Mount Point Crossing 2394 The server file system environment may be constructed in such a way 2395 that one file system contains a directory which is 'covered' or 2396 mounted upon by a second file system. For example: 2398 /a/b (file system 1) 2399 /a/b/c/d (file system 2) 2401 The pseudo file system for this server may be constructed to look 2402 like: 2404 / (place holder/not exported) 2405 /a/b (file system 1) 2406 /a/b/c/d (file system 2) 2408 It is the server's responsibility to present the pseudo file system 2409 that is complete to the client. If the client sends a lookup request 2410 for the path "/a/b/c/d", the server's response is the filehandle of 2411 the file system "/a/b/c/d". In previous versions of the NFS 2412 protocol, the server would respond with the directory "/a/b/c/d" 2413 within the file system "/a/b". 2415 The NFS client will be able to determine if it crosses a server mount 2416 point by a change in the value of the "fsid" attribute. 2418 7.8. Security Policy and Name Space Presentation 2420 The application of the server's security policy needs to be carefully 2421 considered by the implementor. One may choose to limit the 2422 viewability of portions of the pseudo file system based on the 2423 server's perception of the client's ability to authenticate itself 2424 properly. However with the support of multiple security mechanisms 2426 Draft Specification NFS version 4 Protocol February 2000 2428 and the ability to negotiate the appropriate use of these mechanisms, 2429 the server is unable to properly determine if a client will be able 2430 to authenticate itself. If, based on its policies, the server 2431 chooses to limit the contents of the pseudo file system, the server 2432 may effectively hide file systems from a client that may otherwise 2433 have legitimate access. 2435 Draft Specification NFS version 4 Protocol February 2000 2437 8. File Locking and Share Reservations 2439 Integrating locking into the NFS protocol necessarily causes it to be 2440 state-full. With the inclusion of "share" file locks the protocol 2441 becomes substantially more dependent on state than the traditional 2442 combination of NFS and NLM [XNFS]. There are three components to 2443 making this state manageable: 2445 o Clear division between client and server 2447 o Ability to reliably detect inconsistency in state between client 2448 and server 2450 o Simple and robust recovery mechanisms 2452 In this model, the server owns the state information. The client 2453 communicates its view of this state to the server as needed. The 2454 client is also able to detect inconsistent state before modifying a 2455 file. 2457 To support Win32 "share" locks it is necessary to atomically OPEN or 2458 CREATE files. Having a separate share/unshare operation would not 2459 allow correct implementation of the Win32 OpenFile API. In order to 2460 correctly implement share semantics, the previous NFS protocol 2461 mechanisms used when a file is opened or created (LOOKUP, CREATE, 2462 ACCESS) need to be replaced. The NFS version 4 protocol has an OPEN 2463 operation that subsumes the functionality of LOOKUP, CREATE, and 2464 ACCESS. However, because many operations require a filehandle, the 2465 traditional LOOKUP is preserved to map a file name to filehandle 2466 without establishing state on the server. The policy of granting 2467 access or modifying files is managed by the server based on the 2468 client's state. These mechanisms can implement policy ranging from 2469 advisory only locking to full mandatory locking. 2471 8.1. Locking 2473 It is assumed that manipulating a lock is rare when compared to READ 2474 and WRITE operations. It is also assumed that crashes and network 2475 partitions are relatively rare. Therefore it is important that the 2476 READ and WRITE operations have a lightweight mechanism to indicate if 2477 they possess a held lock. A lock request contains the heavyweight 2478 information required to establish a lock and uniquely define the lock 2479 owner. 2481 The following sections describe the transition from the heavy weight 2482 information to the eventual stateid used for most client and server 2483 locking and lease interactions. 2485 Draft Specification NFS version 4 Protocol February 2000 2487 8.1.1. Client ID 2489 For each LOCK request, the client must identify itself to the server. 2490 This is done in such a way as to allow for correct lock 2491 identification and crash recovery. Client identification is 2492 accomplished with two values. 2494 o A verifier that is used to detect client reboots. 2496 o A variable length opaque array to uniquely define a client. 2498 For an operating system this may be a fully qualified host 2499 name or IP address. For a user level NFS client it may 2500 additionally contain a process id or other unique sequence. 2502 The data structure for the Client ID would then appear as: 2504 struct nfs_client_id { 2505 opaque verifier[4]; 2506 opaque id<>; 2507 } 2509 It is possible through the mis-configuration of a client or the 2510 existence of a rogue client that two clients end up using the same 2511 nfs_client_id. This situation is avoided by "negotiating" the 2512 nfs_client_id between client and server with the use of the 2513 SETCLIENTID and SETCLIENTID_CONFIRM operations. The following 2514 describes the two scenarios of negotiation. 2516 1 Client has never connected to the server 2518 In this case the client generates an nfs_client_id and 2519 unless another client has the same nfs_client_id.id field, 2520 the server accepts the request. The server also records the 2521 principal (or principal to uid mapping) from the credential 2522 in the RPC request that contains the nfs_client_id 2523 negotiation request (SETCLIENTID operation). 2525 Two clients might still use the same nfs_client_id.id due 2526 to perhaps configuration error. For example, a High 2527 Availability configuration where the nfs_client_id.id is 2528 derived from the ethernet controller address and both 2529 systems have the same address. In this case, the result is 2530 a switched union that returns in addition to 2531 NFS4ERR_CLID_INUSE, the network address (the rpcbind netid 2532 and universal address) of the client that is using the id. 2534 Draft Specification NFS version 4 Protocol February 2000 2536 2 Client is re-connecting to the server after a client reboot 2538 In this case, the client still generates an nfs_client_id 2539 but the nfs_client_id.id field will be the same as the 2540 nfs_client_id.id generated prior to reboot. If the server 2541 finds that the principal/uid is equal to the previously 2542 "registered" nfs_client_id.id, then locks associated with 2543 the old nfs_client_id are immediately released. If the 2544 principal/uid is not equal, then this is a rogue client and 2545 the request is returned in error. For more discussion of 2546 crash recovery semantics, see the section on "Crash 2547 Recovery" 2549 To mitigate retransmission of the SETCLIENTID operation, 2550 the client and server use a confirmation step. The server 2551 returns a confirmation verifier that the client then sends 2552 to the server in the SETCLIENTID_CONFIRM operation. Once 2553 the server receives the confirmation from the client, the 2554 locking state for the client is released. 2556 In both cases, upon success, NFS4_OK is returned. To help reduce the 2557 amount of data transferred on OPEN and LOCK, the server will also 2558 return a unique 64-bit clientid value that is a shorthand reference 2559 to the nfs_client_id values presented by the client. From this point 2560 forward, the client will use the clientid to refer to itself. 2562 The clientid assigned by the server should be chosen so that it will 2563 not conflict with a clientid previously assigned by the server. This 2564 applies across server restarts or reboots. When a clientid is 2565 presented to a server and that clientid is not recognized, as would 2566 happen after a server reboot, the server will reject the request with 2567 the error NFS4ERR_STALE_CLIENTID. When this happens, the client must 2568 obtain a new clientid by use of the SETCLIENTID operation and then 2569 proceed to any other necessary recovery for the server reboot case 2570 (See the section "Server Failure and Recovery"). 2572 The client must also employ the SETCLIENTID operation when it 2573 receives a NFS4ERR_STALE_STATEID error using a stateid derived from 2574 its current clientid since this also indicates a server reboot which 2575 has invalidated the existing clientid (see the next section 2576 "nfs_lockowner and stateid Definition" for details). 2578 8.1.2. Server Release of Clientid 2580 If the server determines that the client holds no associated state 2581 for its clientid and no activity from that client has been received 2582 some long period of time, the server may choose to release the 2584 Draft Specification NFS version 4 Protocol February 2000 2586 clientid. The server may make this choice for an inactive client so 2587 that resources are not consumed by those intermittently active 2588 clients. If the client contacts the server after the this release, 2589 the server must ensure the client receives the appropriate error so 2590 that it will use the SETCLIENTID/SETCLIENTID_CONFIRM sequence to 2591 establish a new identity. It should be clear that the server must be 2592 very hesitant to release a clientid since the resultant work on the 2593 client to recover from such an event will be the same burden as if 2594 the server had failed and restarted. 2596 8.1.3. nfs_lockowner and stateid Definition 2598 When requesting a lock, the client must present to the server the 2599 clientid and an identifier for the owner of the requested lock. 2600 These two fields are referred to as the nfs_lockowner and the 2601 definition of those fields are: 2603 o A clientid returned by the server as part of the client's use of 2604 the SETCLIENTID operation. 2606 o A variable length opaque array used to uniquely define the owner 2607 of a lock managed by the client. 2609 This may be a thread id, process id, or other unique value. 2611 When the server grants the lock, it responds with a unique 64-bit 2612 stateid. The stateid is used as a shorthand reference to the 2613 nfs_lockowner, since the server will be maintaining the 2614 correspondence between them. 2616 The server is free to form the stateid in any manner that it chooses 2617 as long as it is able to recognize invalid and out-of-date stateids. 2618 This requirement includes those stateids generated by earlier 2619 instances of the server. From this, the client can be properly 2620 notified of a server restart. This notification will occur when the 2621 client presents a stateid to the server from a previous 2622 instantiation. 2624 The server must be able to distinguish the following situations and 2625 return the error as specified: 2627 o The stateid was generated by an earlier server instance (i.e. 2628 before a server reboot). The error NFS4ERR_STALE_STATEID should 2629 be returned. 2631 o The stateid was generated by the current server instance but the 2633 Draft Specification NFS version 4 Protocol February 2000 2635 stateid no longer designates the current locking state for the 2636 lockowner-file pair in question (i.e. one or more locking 2637 operations has occurred). The error NFS4ERR_OLD_STATEID should 2638 be returned. 2640 This error condition will only occur when the client issues a 2641 locking request which changes a stateid while an I/O request 2642 that uses that stateid is outstanding. 2644 o The stateid was generated by the current server instance but the 2645 stateid does not designate a locking state for any active 2646 lockowner-file pair. The error NFS4ERR_BAD_STATEID should be 2647 returned. 2649 This error condition will occur when there has been a logic 2650 error on the part of the client or server. This should not 2651 happen. 2653 One mechanism that may be used to satisfy these requirements is for 2654 the server to divide stateids into three fields: 2656 o A server verifier which uniquely designates a particular server 2657 instantiation. 2659 o An index into a table of locking-state structures. 2661 o A sequence value which is incremented for each stateid that is 2662 associated with the same index into the locking-state table. 2664 By matching the incoming stateid and its field values with the state 2665 held at the server, the server is able to easily determine if a 2666 stateid is valid for its current instantiation and state. If the 2667 stateid is not valid, the appropriate error can be supplied to the 2668 client. 2670 8.1.4. Use of the stateid 2672 All READ and WRITE operations contain a stateid. If the 2673 nfs_lockowner performs a READ or WRITE on a range of bytes within a 2674 locked range, the stateid (previously returned by the server) must be 2675 used to indicate that appropriate lock (record or share) is held. If 2676 no state is established by the client, either record lock or share 2677 lock, a stateid of all bits 0 is used. If no conflicting locks are 2678 held on the file, the server may service the READ or WRITE operation. 2679 If a conflict with an explicit lock occurs, an error is returned for 2680 the operation (NFS4ERR_LOCKED). This allows "mandatory locking" to be 2682 Draft Specification NFS version 4 Protocol February 2000 2684 implemented. 2686 A stateid of all bits 1 (one) allows READ operations to bypass record 2687 locking checks at the server. However, WRITE operations with stateid 2688 with bits all 1 (one) do not bypass record locking checks. File 2689 locking checks are handled by the OPEN operation (see the section 2690 "OPEN/CLOSE Operations"). 2692 An explicit lock may not be granted while a READ or WRITE operation 2693 with conflicting implicit locking is being performed. 2695 8.1.5. Sequencing of Lock Requests 2697 Locking is different than most NFS operations as it requires "at- 2698 most-one" semantics that are not provided by ONCRPC. In the face of 2699 retransmission or reordering, lock or unlock requests must have a 2700 well defined and consistent behavior. To accomplish this, each lock 2701 request contains a sequence number that is a consecutively increasing 2702 integer. Different nfs_lockowners have different sequences. The 2703 server maintains the last sequence number (L) received and the 2704 response that was returned. 2706 If a request with a previous sequence number (r < L) is received, it 2707 is rejected with the return of error NFS4ERR_BAD_SEQID. Given a 2708 properly-functioning client, the response to (r) must have been 2709 received before the last request (L) was sent. If a duplicate of 2710 last request (r == L) is received, the stored response is returned. 2711 If a request beyond the next sequence (r == L + 2) is received, it is 2712 rejected with the return of error NFS4ERR_BAD_SEQID. Sequence 2713 history is reinitialized whenever the client verifier changes. 2715 Since the sequence number is represented with an unsigned 32-bit 2716 integer, the arithmetic involved with the sequence number is mod 2717 2^32. 2719 It is critical the server maintain the last response sent to the 2720 client to provide a more reliable cache of duplicate non-idempotent 2721 requests than that of the traditional cache described in [Juszczak]. 2722 The traditional duplicate request cache uses a least recently used 2723 algorithm for removing unneeded requests. However, the last lock 2724 request and response on a given nfs_lockowner must be cached as long 2725 as the lock state exists on the server. 2727 8.1.6. Recovery from Replayed Requests 2729 As described above, the sequence number is per nfs_lockowner. As 2731 Draft Specification NFS version 4 Protocol February 2000 2733 long as the server maintains the last sequence number received and 2734 follows the methods described above, there are no risks of a 2735 byzantine router re-sending old requests. The server need only 2736 maintain the nfs_lockowner, sequence number state as long as there 2737 are open files or closed files with locks outstanding. 2739 LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence 2740 number and therefore the risk of the replay of these operations 2741 resulting in undesired effects is non-existent while the server 2742 maintains the nfs_lockowner state. 2744 8.1.7. Releasing nfs_lockowner State 2746 When a particular nfs_lockowner no longer holds open or file locking 2747 state at the server, the server may choose to release the sequence 2748 number state associated with the nfs_lockowner. The server may make 2749 this choice based on lease expiration, for the reclamation of server 2750 memory, or other implementation specific details. In any event, the 2751 server is able to do this safely only when the nfs_lockowner no 2752 longer is being utilized by the client. The server may choose to 2753 hold the nfs_lockowner state in the event that retransmitted requests 2754 are received. However, the period to hold this state is 2755 implementation specific. 2757 In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is 2758 retransmitted after the server has previously released the 2759 nfs_lockowner state, the server will find that the nfs_lockowner has 2760 no files open and an error will be returned to the client. If the 2761 nfs_lockowner does have a file open, the stateid will not match and 2762 again an error is returned to the client. 2764 In the case that an OPEN is retransmitted and the nfs_lockowner is 2765 being used for the first time or the nfs_lockowner state has been 2766 previously released by the server, the use of the OPEN_CONFIRM 2767 operation will prevent incorrect behavior. When the server observes 2768 the use of the nfs_lockowner for the first time, it will direct the 2769 client to perform the OPEN_CONFIRM for the corresponding OPEN. This 2770 sequence establishes the use of an nfs_lockowner and associated 2771 sequence number. See the section "OPEN_CONFIRM - Confirm Open" for 2772 further details. 2774 8.2. Lock Ranges 2776 The protocol allows a lock owner to request a lock with one byte 2777 range and then either upgrade or unlock a sub-range of the initial 2778 lock. It is expected that this will be an uncommon type of request. 2780 Draft Specification NFS version 4 Protocol February 2000 2782 In any case, servers or server file systems may not be able to 2783 support sub-range lock semantics. In the event that a server 2784 receives a locking request that represents a sub-range of current 2785 locking state for the lock owner, the server is allowed to return the 2786 error NFS4ERR_LOCK_RANGE to signify that it does not support sub- 2787 range lock operations. Therefore, the client should be prepared to 2788 receive this error and, if appropriate, report the error to the 2789 requesting application. 2791 The client is discouraged from coalescing adjacent ranges since the 2792 server may not support sub-range requests and for reasons related to 2793 the recovery of file locking state in the event of server failure. 2794 As discussed in the section "Server Failure and Recovery" below, the 2795 server may employ certain optimizations during recovery that work 2796 effectively only when the client's behavior during lock recovery is 2797 similar to the client's locking behavior prior to server failure. 2799 8.3. Blocking Locks 2801 Some clients require the support of blocking locks. The NFS version 2802 4 protocol must not rely on a callback mechanism and therefore is 2803 unable to notify a client when a previously denied lock has been 2804 granted. Clients have no choice but to continually poll for the 2805 lock. This presents a fairness problem. Two new lock types are 2806 added, READW and WRITEW, and are used to indicate to the server that 2807 the client is requesting a blocking lock. The server should maintain 2808 an ordered list of pending blocking locks. When the conflicting lock 2809 is released, the server may wait the lease period for the first 2810 waiting client to re-request the lock. After the lease period 2811 expires the next waiting client request is allowed the lock. Clients 2812 are required to poll at an interval sufficiently small that it is 2813 likely to acquire the lock in a timely manner. The server is not 2814 required to maintain a list of pending blocked locks as it is used to 2815 increase fairness and not correct operation. Because of the 2816 unordered nature of crash recovery, storing of lock state to stable 2817 storage would be required to guarantee ordered granting of blocking 2818 locks. 2820 Servers may also note the lock types and delay returning denial of 2821 the request to allow extra time for a conflicting lock to be 2822 released, allowing a successful return. In this way, clients can be 2823 avoid the burden of needlessly frequent polling for blocking locks. 2824 The server should take care in the length of delay in the event the 2825 client retransmits the request. 2827 Draft Specification NFS version 4 Protocol February 2000 2829 8.4. Lease Renewal 2831 The purpose of a lease is to allow a server to remove stale locks 2832 that are held by a client that has crashed or is otherwise 2833 unreachable. It is not a mechanism for cache consistency and lease 2834 renewals may not be denied if the lease interval has not expired. 2836 The following events cause implicit renewal of all of the leases for 2837 a given client (i.e. all those sharing a given clientid). Each of 2838 these is a positive indication that the client is still active and 2839 that the associated state held at the server, for the client, is 2840 still valid. 2842 o An OPEN with a valid clientid. 2844 o Any operation made with a valid stateid (CLOSE, DELEGRETURN, 2845 LOCK, LOCKU, OPEN, OPEN_CONFIRM, READ, RENEW, SETATTR, WRITE). 2846 This does not include the special stateids of all bits 0 or all 2847 bits 1. 2849 Note that if the client had restarted or rebooted, the 2850 client would not be making these requests without issuing 2851 the SETCLIENTID operation. The use of the SETCLIENTID 2852 operation (possibly with the addition of the optional 2853 SETCLIENTID_CONFIRM operation) notifies the server to drop 2854 the locking state associated with the client. 2856 If the server has rebooted, the stateids 2857 (NFS4ERR_STALE_STATEID error) or the clientid 2858 (NFS4ERR_STALE_CLIENTID error) will not be valid hence 2859 preventing spurious renewals. 2861 This approach allows for low overhead lease renewal which scales 2862 well. In the typical case no extra RPC calls are required for lease 2863 renewal and in the worst case one RPC is required every lease period 2864 (i.e. a RENEW operation). The number of locks held by the client is 2865 not a factor since all state for the client is involved with the 2866 lease renewal action. 2868 Since all operations that create a new lease also renew existing 2869 leases, the server must maintain a common lease expiration time for 2870 all valid leases for a given client. This lease time can then be 2871 easily updated upon implicit lease renewal actions. 2873 8.5. Crash Recovery 2875 The important requirement in crash recovery is that both the client 2877 Draft Specification NFS version 4 Protocol February 2000 2879 and the server know when the other has failed. Additionally, it is 2880 required that a client sees a consistent view of data across server 2881 restarts or reboots. All READ and WRITE operations that may have 2882 been queued within the client or network buffers must wait until the 2883 client has successfully recovered the locks protecting the READ and 2884 WRITE operations. 2886 8.5.1. Client Failure and Recovery 2888 In the event that a client fails, the server may recover the client's 2889 locks when the associated leases have expired. Conflicting locks 2890 from another client may only be granted after this lease expiration. 2891 If the client is able to restart or reinitialize within the lease 2892 period the client may be forced to wait the remainder of the lease 2893 period before obtaining new locks. 2895 To minimize client delay upon restart, lock requests are associated 2896 with an instance of the client by a client supplied verifier. This 2897 verifier is part of the initial SETCLIENTID call made by the client. 2898 The server returns a clientid as a result of the SETCLIENTID 2899 operation. The client then confirms the use of the verifier with 2900 SETCLIENTID_CONFIRM. The clientid in combination with an opaque 2901 owner field is then used by the client to identify the lock owner for 2902 OPEN. This chain of associations is then used to identify all locks 2903 for a particular client. 2905 Since the verifier will be changed by the client upon each 2906 initialization, the server can compare a new verifier to the verifier 2907 associated with currently held locks and determine that they do not 2908 match. This signifies the client's new instantiation and subsequent 2909 loss of locking state. As a result, the server is free to release 2910 all locks held which are associated with the old clientid which was 2911 derived from the old verifier. 2913 For secure environments, a change in the verifier must only cause the 2914 release of locks associated with the authenticated requester. This 2915 is required to prevent a rogue entity from freeing otherwise valid 2916 locks. 2918 Note that the verifier must have the same uniqueness properties of 2919 the verifier for the COMMIT operation. 2921 8.5.2. Server Failure and Recovery 2923 If the server loses locking state (usually as a result of a restart 2924 or reboot), it must allow clients time to discover this fact and re- 2926 Draft Specification NFS version 4 Protocol February 2000 2928 establish the lost locking state. The client must be able to re- 2929 establish the locking state without having the server deny valid 2930 requests because the server has granted conflicting access to another 2931 client. Likewise, if there is the possibility that clients have not 2932 yet re-established their locking state for a file, the server must 2933 disallow READ and WRITE operations for that file. The duration of 2934 this recovery period is equal to the duration of the lease period. 2936 A client can determine that server failure (and thus loss of locking 2937 state) has occurred, when it receives one of two errors. The 2938 NFS4ERR_STALE_STATEID error indicates a stateid invalidated by a 2939 reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a 2940 clientid invalidated by reboot or restart. When either of these are 2941 received, the client must establish a new clientid (See the section 2942 "Client ID") and re-establish the locking state as discussed below. 2944 The period of special handling of locking and READs and WRITEs, equal 2945 in duration to the lease period, is referred to as the "grace 2946 period". During the grace period, clients recover locks and the 2947 associated state by reclaim-type locking requests (i.e. LOCK requests 2948 with reclaim set to true and OPEN operations with a claim type of 2949 CLAIM_PREVIOUS). During the grace period, the server must reject 2950 READ and WRITE operations and non-reclaim locking requests (i.e. 2951 other LOCK and OPEN operations) with an error of NFS4ERR_GRACE. 2953 If the server can reliably determine that granting a non-reclaim 2954 request will not conflict with reclamation of locks by other clients, 2955 the NFS4ERR_GRACE error does not have to be returned and the non- 2956 reclaim client request can be serviced. For the server to be able to 2957 service READ and WRITE operations during the grace period, it must 2958 again be able to guarantee that no possible conflict could arise 2959 between an impending reclaim locking request and the READ or WRITE 2960 operation. If the server is unable to offer that guarantee, the 2961 NFS4ERR_GRACE error must be returned to the client. 2963 For a server to provide simple, valid handling during the grace 2964 period, the easiest method is to simply reject all non-reclaim 2965 locking requests and READ and WRITE operations by returning the 2966 NFS4ERR_GRACE error. However, a server may keep information about 2967 granted locks in stable storage. With this information, the server 2968 could determine if a regular lock or READ or WRITE operation can be 2969 safely processed. 2971 For example, if a count of locks on a given file is available in 2972 stable storage, the server can track reclaimed locks for the file and 2973 when all reclaims have been processed, non-reclaim locking requests 2974 may be processed. This way the server can ensure that non-reclaim 2975 locking requests will not conflict with potential reclaim requests. 2977 Draft Specification NFS version 4 Protocol February 2000 2979 With respect to I/O requests, if the server is able to determine that 2980 there are no outstanding reclaim requests for a file by information 2981 from stable storage or another similar mechanism, the processing of 2982 I/O requests could proceed normally for the file. 2984 To reiterate, for a server that allows non-reclaim lock and I/O 2985 requests to be processed during the grace period, it MUST determine 2986 that no lock subsequently reclaimed will be rejected and that no lock 2987 subsequently reclaimed would have prevented any I/O operation 2988 processed during the grace period. 2990 Clients should be prepared for the return of NFS4ERR_GRACE errors for 2991 non-reclaim lock and I/O requests. In this case the client should 2992 employ a backoff and retry mechanism for the request. Timeout 2993 periods should be chosen to avoid overwhelming a server. The client 2994 must account for the server that is able to perform I/O and non- 2995 reclaim locking requests within the grace period as well as those 2996 that can not do so. 2998 A reclaim-type locking request outside the server's grace period can 2999 only succeed if the server can guarantee that no conflicting lock or 3000 I/O request has been granted since reboot or restart. 3002 8.5.3. Network Partitions and Recovery 3004 If the duration of a network partition is greater than the lease 3005 period provided by the server, the server will have not received a 3006 lease renewal from the client. If this occurs, the server may free 3007 all locks held for the client. As a result, all stateids held by the 3008 client will become invalid or stale. Once the client is able to 3009 reach the server after such a network partition, all I/O submitted by 3010 the client with the now invalid stateids will fail with the server 3011 returning the error NFS4ERR_EXPIRED. Once this error is received, 3012 the client will suitably notify the application that held the lock. 3014 As a courtesy to the client or as an optimization, the server may 3015 continue to hold locks on behalf of a client for which recent 3016 communication has extended beyond the lease period. If the server 3017 receives a lock or I/O request that conflicts with one of these 3018 courtesy locks, the server must free the courtesy lock and grant the 3019 new request. 3021 In the event of a network partition with a duration extending beyond 3022 the expiration of a client's leases, the server MUST employ a method 3023 of recording this fact in its stable storage. Conflicting locks 3024 requests from another client may be serviced after the lease 3025 expiration. There are various scenarios involving server failure 3027 Draft Specification NFS version 4 Protocol February 2000 3029 after such an event that require the storage of these lease 3030 expirations or network partitions. One scenario is as follows: 3032 A client holds a lock at the server and encounters a 3033 network partition and is unable to renew the associated 3034 lease. A second client obtains a conflicting lock and then 3035 frees the lock. After the unlock request by the second 3036 client, the server reboots or reinitializes. Once the 3037 server recovers, the network partition heals and the 3038 original client attempts to reclaim the original lock. 3040 In this scenario and without any state information, the server will 3041 allow the reclaim and the client will be in an inconsistent state 3042 because the server or the client has no knowledge of the conflicting 3043 lock. 3045 The server may choose to store this lease expiration or network 3046 partitioning state in a way that will only identify the client as a 3047 whole. Note that this may potentially lead to lock reclaims being 3048 denied unnecessarily because of a mix of conflicting and non- 3049 conflicting locks. The server may also choose to store information 3050 about each lock that has an expired lease with an associated 3051 conflicting lock. The choice of the amount and type of state 3052 information that is stored is left to the implementor. In any case, 3053 the server must have enough state information to enable correct 3054 recovery from multiple partitions and multiple server failures. 3056 8.6. Recovery from a Lock Request Timeout or Abort 3058 In the event a lock request times out, a client may decide to not 3059 retry the request. The client may also abort the request when the 3060 process for which it was issued is terminated (e.g. in UNIX due to a 3061 signal. It is possible though that the server received the request 3062 and acted upon it. This would change the state on the server without 3063 the client being aware of the change. It is paramount that the 3064 client re-synchronize state with server before it attempts any other 3065 operation that takes a seqid and/or a stateid with the same 3066 nfs_lockowner. This is straightforward to do without a special re- 3067 synchronize operation. 3069 Since the server maintains the last lock request and response 3070 received on the nfs_lockowner, for each nfs_lockowner, the client 3071 should cache the last lock request it sent such that the lock request 3072 did not receive a response. From this, the next time the client does 3073 a lock operation for the nfs_lockowner, it can send the cached 3074 request, if there is one, and if the request was one that established 3076 Draft Specification NFS version 4 Protocol February 2000 3078 state (e.g. a LOCK or OPEN operation) the client can follow up with a 3079 request to remove the state (e.g. a LOCKU or CLOSE operation). With 3080 this approach, the sequencing and stateid information on the client 3081 and server for the given nfs_lockowner will re-synchronize and in 3082 turn the lock state will re-synchronize. 3084 8.7. Server Revocation of Locks 3086 At any point, the server can revoke locks held by a client and the 3087 client must be prepared for this event. When the client detects that 3088 its locks have been or may have been revoked, the client is 3089 responsible for validating the state information between itself and 3090 the server. Validating locking state for the client means that it 3091 must verify or reclaim state for each lock currently held. 3093 The first instance of lock revocation is upon server reboot or re- 3094 initialization. In this instance the client will receive an error 3095 (NFS4ERR_STALE_STATEID or NFS4ERR_STALE_CLIENTID) and the client will 3096 proceed with normal crash recovery as described in the previous 3097 section. 3099 The second lock revocation event can occur as a result of 3100 administrative intervention within the lease period. While this is 3101 considered a rare event, it is possible that the server's 3102 administrator has decided to release or revoke a particular lock held 3103 by the client. As a result of revocation, the client will receive an 3104 error of NFS4ERR_EXPIRED and the error is received within the lease 3105 period for the lock. In this instance the client may assume that 3106 only the nfs_lockowner's locks have been lost. The client notifies 3107 the lock holder appropriately. The client may not assume the lease 3108 period has been renewed as a result of failed operation. 3110 The third lock revocation event is the inability to renew the lease 3111 period. While this is considered a rare or unusual event, the client 3112 must be prepared to recover. Both the server and client will be able 3113 to detect the failure to renew the lease and are capable of 3114 recovering without data corruption. For the server, it tracks the 3115 last renewal event serviced for the client and knows when the lease 3116 will expire. Similarly, the client must track operations which will 3117 renew the lease period. Using the time that each such request was 3118 sent and the time that the corresponding reply was received, the 3119 client should bound the time that the corresponding renewal could 3120 have occurred on the server and thus determine if it is possible that 3121 a lease period expiration could have occurred. 3123 When the client determines the lease period may have expired, the 3124 client must mark all locks held for the associated lease as 3126 Draft Specification NFS version 4 Protocol February 2000 3128 "unvalidated". This means the client has been unable to re-establish 3129 or confirm the appropriate lock state with the server. As described 3130 in the previous section on crash recovery, there are scenarios in 3131 which the server may grant conflicting locks after the lease period 3132 has expired for a client. When it is possible that the lease period 3133 has expired, the client must validate each lock currently held to 3134 ensure that a conflicting lock has not been granted. The client may 3135 accomplish this task by issuing an I/O request, either a pending I/O 3136 or a zero-length read, specifying the stateid associated with the 3137 lock in question. If the response to the request is success, the 3138 client has validated all of the locks governed by that stateid and 3139 re-established the appropriate state between itself and the server. 3140 If the I/O request is not successful, then one or more of the locks 3141 associated with the stateid was revoked by the server and the client 3142 must notify the owner. 3144 8.8. Share Reservations 3146 A share reservation is a mechanism to control access to a file. It 3147 is a separate and independent mechanism from record locking. When a 3148 client opens a file, it issues an OPEN operation to the server 3149 specifying the type of access required (READ, WRITE, or BOTH) and the 3150 type of access to deny others (deny NONE, READ, WRITE, or BOTH). If 3151 the OPEN fails the client will fail the application's open request. 3153 Pseudo-code definition of the semantics: 3155 if ((request.access & file_state.deny)) || 3156 (request.deny & file_state.access)) 3157 return (NFS4ERR_DENIED) 3159 The constants used for the OPEN and OPEN_DOWNGRADE operations for the 3160 access and deny fields are as follows: 3162 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 3163 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 3164 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 3166 const OPEN4_SHARE_DENY_NONE = 0x00000000; 3167 const OPEN4_SHARE_DENY_READ = 0x00000001; 3168 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 3169 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 3171 Draft Specification NFS version 4 Protocol February 2000 3173 8.9. OPEN/CLOSE Operations 3175 To provide correct share semantics, a client MUST use the OPEN 3176 operation to obtain the initial filehandle and indicate the desired 3177 access and what if any access to deny. Even if the client intends to 3178 use a stateid of all 0's or all 1's, it must still obtain the 3179 filehandle for the regular file with the OPEN operation so the 3180 appropriate share semantics can be applied. For clients that do not 3181 have a deny mode built into their open programming interfaces, deny 3182 equal to NONE should be used. 3184 The OPEN operation with the CREATE flag, also subsumes the CREATE 3185 operation for regular files as used in previous versions of the NFS 3186 protocol. This allows a create with a share to be done atomically. 3188 The CLOSE operation removes all share locks held by the nfs_lockowner 3189 on that file. If record locks are held, the client SHOULD release 3190 all locks before issuing a CLOSE. The server MAY free all 3191 outstanding locks on CLOSE but some servers may not support the CLOSE 3192 of a file that still has record locks held. The server MUST return 3193 failure if any locks would exist after the CLOSE. 3195 The LOOKUP operation is preserved and will return a filehandle 3196 without establishing any lock state on the server. Without a valid 3197 stateid, the server will assume the client has the least access. For 3198 example, a file opened with deny READ/WRITE cannot be accessed using 3199 a filehandle obtained through LOOKUP because it would not have a 3200 valid stateid (i.e. using a stateid of all bits 0 or all bits 1). 3202 8.10. Open Upgrade and Downgrade 3204 When an OPEN is done for a file and the lockowner for which the open 3205 is being done already has the file open, the result is to upgrade the 3206 open file status maintained on the server to include the access and 3207 deny bits specified by the new OPEN as well as those for the existing 3208 OPEN. The result is that there is one open file, as far as the 3209 protocol is concerned, and it includes the union of the access and 3210 deny bits for all of the OPEN requests completed. Only a single 3211 CLOSE will be done to reset the effects of both OPEN's. Note that 3212 the client, when issuing the OPEN, may not know that the same file is 3213 in fact being opened. The above only applies if both OPEN's result 3214 in the OPEN'ed object being designated by the same filehandle. 3216 When the server chooses to export multiple filehandles corresponding 3217 to the same file object and returns different filehandles on two 3218 different OPEN's of the same file object, the server MUST NOT "OR" 3219 together the access and deny bits and coalesce the two open files. 3221 Draft Specification NFS version 4 Protocol February 2000 3223 Instead the server must maintain separate OPEN's with separate 3224 stateid's and will require separate CLOSE's to free them. 3226 When multiple open files on the client are merged into a single open 3227 file object on the server, the close of one of the open files (on the 3228 client) may necessitate change of the access and deny status of the 3229 open file on the server. This is because the union of the access and 3230 deny bits for the remaining open's may be smaller (i.e. a proper 3231 subset) than previously. The OPEN_DOWNGRADE operation is used to 3232 make the necessary change and the client should use it to update the 3233 server so that share reservation requests by other clients are 3234 handled properly. 3236 8.11. Short and Long Leases 3238 When determining the time period for the server lease, the usual 3239 lease tradeoffs apply. Short leases are good for fast server 3240 recovery at a cost of increased RENEW or READ (with zero length) 3241 requests. Longer leases are certainly kinder and gentler to large 3242 internet servers trying to handle a very large numbers of clients. 3243 The number of RENEW requests drop in proportion to the lease time. 3244 The disadvantages of long leases are slower recovery after server 3245 failure (server must wait for leases to expire and grace period 3246 before granting new lock requests) and increased file contention (if 3247 client fails to transmit an unlock request then server must wait for 3248 lease expiration before granting new locks). 3250 Long leases are usable if the server is able to store lease state in 3251 non-volatile memory. Upon recovery, the server can reconstruct the 3252 lease state from its non-volatile memory and continue operation with 3253 its clients and therefore long leases are not an issue. 3255 8.12. Clocks and Calculating Lease Expiration 3257 To avoid the need for synchronized clocks, lease times are granted by 3258 the server as a time delta. However, there is a requirement that the 3259 client and server clocks do not drift excessively over the duration 3260 of the lock. There is also the issue of propagation delay across the 3261 network which could easily be several hundred milliseconds as well as 3262 the possibility that requests will be lost and need to be 3263 retransmitted. 3265 To take propagation delay into account, the client should subtract it 3266 from lease times (e.g. if the client estimates the one-way 3267 propagation delay as 200 msec, then it can assume that the lease is 3268 already 200 msec old when it gets it). In addition, it will take 3270 Draft Specification NFS version 4 Protocol February 2000 3272 another 200 msec to get a response back to the server. So the client 3273 must send a lock renewal or write data back to the server 400 msec 3274 before the lease would expire. 3276 8.13. Migration, Replication and State 3278 When responsibility for handling a given file system is transferred 3279 to a new server (migration) or the client chooses to use an alternate 3280 server (e.g. in response to server unresponsiveness) in the context 3281 of file system replication, the appropriate handling of state shared 3282 between the client and server (i.e. locks, leases, stateid's, and 3283 clientid's) is as described below. The handling differs between 3284 migration and replication. For related discussion of file server 3285 state and recover of such see the sections under "File Locking and 3286 Share Reservations" 3288 8.13.1. Migration and State 3290 In the case of migration, the servers involved in the migration of a 3291 file system should transfer all server state from the original to the 3292 new server. This must be done in a way that is transparent to the 3293 client. This state transfer will ease the client's transition when a 3294 file system migration occurs. If the servers are successful in 3295 transferring all state, the client will continue to use stateid's 3296 assigned by the original server. Therefore the new server must 3297 recognized these stateid's as valid. This holds true for the 3298 clientid as well. Since responsibility for an entire file system is 3299 transferred with a migration event, there is no possibility that 3300 conflicts will arise on the new server as a result of the transfer of 3301 locks. 3303 As part of the transfer of information between servers, leases would 3304 be transferred as well. The leases being transferred to the new 3305 server will typically have a different expiration time from those for 3306 the same client, previously on the new server. To maintain the 3307 property that all leases on a given server for a given client expire 3308 at the same time, the server should advance the expiration time to 3309 the later of the leases being transferred or the leases already 3310 present. This allows the client to maintain lease renewal of both 3311 classes without special effort. 3313 The servers may choose not to transfer the state information upon 3314 migration. However, this choice is discouraged. In this case, when 3315 the client presents state information from the original server, the 3316 client must be prepared to receive either NFS4ERR_STALE_CLIENTID or 3318 Draft Specification NFS version 4 Protocol February 2000 3320 NFS4ERR_STALE_STATEID from the new server. The client should then 3321 recover its state information as it normally would in response to a 3322 server failure. The new server must take care to allow for the 3323 recovery of state information as it would in the event of server 3324 restart. 3326 8.13.2. Replication and State 3328 Since client switch-over in the case of replication is not under 3329 server control, the handling of state is different. In this case, 3330 leases, stateid's and clientid's do not have validity across a 3331 transition from one server to another. The client must re-establish 3332 its locks on the new server. This can be compared to the re- 3333 establishment of locks by means of reclaim-type requests after a 3334 server reboot. The difference is that the server has no provision to 3335 distinguish requests reclaiming locks from those obtaining new locks 3336 or to defer the latter. Thus, a client re-establishing a lock on the 3337 new server (by means of a LOCK or OPEN request), may have the 3338 requests denied due to a conflicting lock. Since replication is 3339 intended for read-only use of filesystems, such denial of locks 3340 should not pose large difficulties in practice. When an attempt to 3341 re-establish a lock on a new server is denied, the client should 3342 treat the situation as if his original lock had been revoked. 3344 8.13.3. Notification of Migrated Lease 3346 In the case of lease renewal, the client may not be submitting 3347 requests for a file system that has been migrated to another server. 3348 This can occur because of the implicit lease renewal mechanism. The 3349 client renews leases for all file systems when submitting a request 3350 to any one file system at the server. 3352 In order for the client to schedule renewal of leases that may have 3353 been relocated to the new server, the client must find out about 3354 lease relocation before those leases expire. To accomplish this, all 3355 operations which implicitly renew leases for a client (i.e. OPEN, 3356 CLOSE, READ, WRITE, RENEW, LOCK, LOCKT, LOCKU), will return the error 3357 NFS4ERR_LEASE_MOVED if responsibility for any of the leases to be 3358 renewed has been transferred to a new server. This condition will 3359 continue until the client receives an NFS4ERR_MOVED error for an 3360 access to each file system for which a lease has been moved to a new 3361 server. 3363 When a client receives an NFS4ERR_LEASE_MOVED error, it should 3364 perform some operation, such as a RENEW, on each file system 3365 associated with the server in question. When the client receives an 3367 Draft Specification NFS version 4 Protocol February 2000 3369 NFS4ERR_MOVED error, the client can follow the normal process to 3370 obtain the new server information (through the fs_locations 3371 attribute) and perform renewal of those leases on the new server. If 3372 the server has not had state transferred to it transparently, it will 3373 receive either NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from 3374 the new server, as described above, and can then recover state 3375 information as it does in the event of server failure. 3377 Draft Specification NFS version 4 Protocol February 2000 3379 9. Client-Side Caching 3381 Client-side caching of data, of file attributes, and of file names is 3382 essential to providing good performance with the NFS protocol. 3383 Providing distributed cache coherence is a difficult problem and 3384 previous versions of the NFS protocol have not attempted it. 3385 Instead, several NFS client implementation techniques have been used 3386 to reduce the problems that a lack of coherence poses for users. 3387 These techniques have not been clearly defined by earlier protocol 3388 specifications and it is often unclear what is valid or invalid 3389 client behavior. 3391 The NFS version 4 protocol uses many techniques similar to those that 3392 have been used in previous protocol versions. The NFS version 4 3393 protocol does not provide distributed cache coherence. However, it 3394 defines a more limited set of caching guarantees to allow locks and 3395 share reservations to be used without destructive interference from 3396 client side caching. 3398 In addition, the NFS version 4 protocol introduces a delegation 3399 mechanism which allows many decisions normally made by the server to 3400 be made locally by clients. This mechanism provides efficient 3401 support of the common cases where sharing is infrequent or where 3402 sharing is read-only. 3404 9.1. Performance Challenges for Client-Side Caching 3406 Caching techniques used in previous versions of the NFS protocol have 3407 been successful in providing good performance. However, several 3408 scalability challenges can arise when those techniques are used with 3409 very large numbers of clients. This is particularly true when 3410 clients are geographically distributed which classically increases 3411 the latency for cache revalidation requests. 3413 The previous versions of the NFS protocol repeat their file data 3414 cache validation requests at the time the file is opened. This 3415 behavior can have serious performance drawbacks. A common case is 3416 one in which a file is only accessed by a single client. Therefore, 3417 sharing is infrequent. 3419 In this case, repeated reference to the server to find that no 3420 conflicts exist is expensive. A better option with regards to 3421 performance is to allow a client that repeatedly opens a file to do 3422 so without reference to the server. This is done until potentially 3423 conflicting operations from another client actually occur. 3425 A similar situation arises in connection with file locking. Sending 3427 Draft Specification NFS version 4 Protocol February 2000 3429 file lock and unlock requests to the server as well as the read and 3430 write requests necessary to make data caching consistent with the 3431 locking semantics (see the section "Data Caching and File Locking") 3432 can severely limit performance. When locking is used to provide 3433 protection against infrequent conflicts, a large penalty is incurred. 3434 This penalty may discourage the use of file locking by applications. 3436 The NFS version 4 protocol provides more aggressive caching 3437 strategies with the following design goals: 3439 o Compatibility with a large range of server semantics. 3441 o Provide the same caching benefits as previous versions of the 3442 NFS protocol when unable to provide the more aggressive model. 3444 o Requirements for aggressive caching are organized so that a 3445 large portion of the benefit can be obtained even when not all 3446 of the requirements can be met. 3448 The appropriate requirements for the server are discussed in later 3449 sections in which specific forms of caching are covered. (see the 3450 section "Open Delegation"). 3452 9.2. Delegation and Callbacks 3454 Recallable delegation of server responsibilities for a file to a 3455 client improves performance by avoiding repeated requests to the 3456 server in the absence of inter-client conflict. With the use of a 3457 "callback" RPC from server to client, a server recalls delegated 3458 responsibilities when another client engages in sharing of a 3459 delegated file. 3461 A delegation is passed from the server to the client, specifying the 3462 object of the delegation and the type of delegation. There are 3463 different types of delegations but each type contains a stateid to be 3464 used to represent the delegation when performing operations that 3465 depend on the delegation. This stateid is similar to those 3466 associated with locks and share reservations but differs in that the 3467 stateid for a delegation is associated with a clientid and may be 3468 used on behalf of all the nfs_lockowners for the given client. A 3469 delegation is made to the client as a whole and not to any specific 3470 process or thread of control within it. 3472 Because callback RPCs may not work in all environments (due to 3473 firewalls, for example), correct protocol operation does not depend 3474 on them. Preliminary testing of callback functionality by means of a 3476 Draft Specification NFS version 4 Protocol February 2000 3478 CB_NULL procedure determines whether callbacks can be supported. The 3479 CB_NULL procedure checks the continuity of the callback path. A 3480 server makes a preliminary assessment of callback availability to a 3481 given client and avoids delegating responsibilities until it has 3482 determined that callbacks are supported. Because the granting of a 3483 delegation is always conditional upon the absence of conflicting 3484 access, clients must not assume that a delegation will be granted and 3485 they must always be prepared for OPENs to be processed without any 3486 delegations being granted. 3488 Once granted, a delegation behaves in most ways like a lock. There 3489 is an associated lease that is subject to renewal together with all 3490 of the other leases held by that client. 3492 Unlike locks, an operation by a second client to a delegated file 3493 will cause the server to recall a delegation through a callback. 3495 On recall, the client holding the delegation must flush modified 3496 state (such as modified data) to the server and return the 3497 delegation. The conflicting request will not receive a response 3498 until the recall is complete. The recall is considered complete when 3499 the client returns the delegation or the server times out on the 3500 recall and revokes the delegation as a result of the timeout. 3501 Following the resolution of the recall, the server has the 3502 information necessary to grant or deny the second client's request. 3504 At the time the client receives a delegation recall, it may have 3505 substantial state that needs to be flushed to the server. Therefore, 3506 the server should allow sufficient time for the recall RPC to 3507 complete since it may involve numerous RPCs to the server. If the 3508 server is able to determine that the client is diligently flushing 3509 state to the server as a result of the recall, the server may extend 3510 the usual time allowed for a recall. However, the time allowed for 3511 recall completion should not be unbounded. 3513 An example of this is when responsibility to mediate opens on a given 3514 file is delegated to a client (see the section "Open Delegation"). 3515 The server will not know what opens are in effect on the client. 3516 Without this knowledge the server will be unable to determine if the 3517 access and deny state for the file allows any particular open until 3518 the delegation for the file has been returned. 3520 A client failure or a network partition can result in failure to 3521 respond to a recall callback. In this case, the server will revoke 3522 the delegation which in turn will render useless any modified state 3523 still on the client. 3525 Draft Specification NFS version 4 Protocol February 2000 3527 9.2.1. Delegation Recovery 3529 There are three situations that delegation recovery must deal with: 3531 o Client reboot or restart 3533 o Server reboot or restart 3535 o Network partition (full or callback-only) 3537 In the event the client reboots or restarts, the failure to renew 3538 leases will result in the revocation of record locks and share 3539 reservations. Delegations, however, may treated a bit differently. 3541 There will be situations in which delegations will need to be 3542 reestablished after a client reboots or restarts. The reason for 3543 this is the client may have file data stored locally and this data 3544 was associated with the previously held delegations. The client will 3545 need to reestablish the appropriate file state on the server. 3547 To allow for this type of client recovery, the server may extend the 3548 period for delegation recovery beyond the typical lease expiration 3549 period. This implies that requests from other clients that conflict 3550 with these delegations will need to wait. This behavior is 3551 consistent with the normal recall process may take significant time 3552 because of the client's need to flush state to the server. This 3553 longer interval would increase the window for clients to reboot and 3554 consult stable storage so that the delegations can be reclaimed. For 3555 open delegations, such delegations are reclaimed using OPEN with a 3556 claim type of CLAIM_DELEGATE_PREV. (see the sections on "Data 3557 Caching and Revocation" and "Operation 18: OPEN" for discussion of 3558 open delegation and the details of OPEN respectively). 3560 When the server reboots or restarts, delegations are reclaimed (using 3561 the OPEN operation with CLAIM_DELEGATE_PREV) in a similar fashion to 3562 record locks and share reservations. However, there is a slight 3563 semantic difference. In the normal case if the server decides that a 3564 delegation should not be granted, it performs the requested action 3565 (e.g. OPEN) without granting any delegation. For reclaim, the server 3566 grants the delegation but a special designation is applied so that 3567 the client treats the delegation as having been granted but recalled 3568 by the server. Because of this, the client has the duty to write all 3569 modified state to the server and then return the delegation. This 3570 process of handling delegation reclaim reconciles three principles of 3571 the NFS Version 4 protocol: 3573 Draft Specification NFS version 4 Protocol February 2000 3575 o Upon reclaim, a client reporting resources assigned to it by an 3576 earlier server instance must be granted those resources. 3578 o The server has unquestionable authority to determine whether 3579 delegations are to be granted and, once granted, whether they 3580 are to be continued. 3582 o The use of callbacks is not to be depended upon until the client 3583 has proven its ability to receive them. 3585 When a network partition occurs, delegations are subject to freeing 3586 by the server when the lease renewal period expires. This is similar 3587 to the behavior for locks and share reservations. For delegations, 3588 however, the server may extend the period in which conflicting 3589 requests are held off. Eventually the occurrence of a conflicting 3590 request from another client will cause revocation of the delegation. 3591 A loss of the callback path (e.g. by later network configuration 3592 change) will have the same effect. A recall request will fail and 3593 revocation of the delegation will result. 3595 A client normally finds out about revocation of a delegation when it 3596 uses a stateid associated with a delegation and receives the error 3597 NFS4ERR_EXPIRED. It also may find out about delegation revocation 3598 after a client reboot when it attempts to reclaim a delegation and 3599 receives that same error. Note that in the case of a revoked write 3600 open delegation, there are issues because data may have been modified 3601 by the client whose delegation is revoked and separately by other 3602 clients. See the section "Revocation Recovery for Write Open 3603 Delegation" for a discussion of such issues. Note also that when 3604 delegations are revoked, information about the revoked delegation 3605 will be written by the server to stable storage (as described in the 3606 section "Crash Recovery"). This is done to deal with the case in 3607 which a server reboots after revoking a delegation but before the 3608 client holding the revoked delegation is notified about the 3609 revocation. 3611 9.3. Data Caching 3613 When applications share access to a set of files, they need to be 3614 implemented so as to take account of the possibility of conflicting 3615 access by another application. This is true whether the applications 3616 in question execute on different clients or reside on the same 3617 client. 3619 Share reservations and record locks are the facilities the NFS 3620 version 4 protocol provides to allow applications to coordinate 3621 access by providing mutual exclusion facilities. The NFS version 4 3623 Draft Specification NFS version 4 Protocol February 2000 3625 protocol's data caching must be implemented such that it does not 3626 invalidate the assumptions that those using these facilities depend 3627 upon. 3629 9.3.1. Data Caching and OPENs 3631 In order to avoid invalidating the sharing assumptions that 3632 applications rely on, NFS version 4 clients should not provide cached 3633 data to applications or modify it on behalf of an application when it 3634 would not be valid to obtain or modify that same data via a READ or 3635 WRITE operation. 3637 Furthermore, in the absence of open delegation (see the section "Open 3638 Delegation") two additional rules apply. Note that these rules are 3639 obeyed in practice by many NFS version 2 and version 3 clients. 3641 o First, cached data present on a client must be revalidated after 3642 doing an OPEN. This is to ensure that the data for the OPENed 3643 file is still correctly reflected in the client's cache. This 3644 validation must be done at least when the client's OPEN 3645 operation includes DENY=WRITE or BOTH thus terminating a period 3646 in which other clients may have had the opportunity to open the 3647 file with WRITE access. Clients may choose to do the 3648 revalidation more often (i.e. at OPENs specifying DENY=NONE) to 3649 parallel the NFS version 3 protocol's practice for the benefit 3650 of users assuming this degree of cache revalidation. 3652 o Second, modified data must be flushed to the server before 3653 closing a file OPENed for write. This is complementary to the 3654 first rule. If the data is not flushed at CLOSE, the 3655 revalidation done after client OPENs as file is unable to 3656 achieve its purpose. The other aspect to flushing the data 3657 before close is that the data must be committed to stable 3658 storage before the CLOSE operation is requested by the client. 3659 In the case of a server reboot or restart and a CLOSEd file, it 3660 may not be possible to retransmit the data to be written to the 3661 file. Hence, this requirement. 3663 9.3.2. Data Caching and File Locking 3665 For those applications that choose to use file locking instead of 3666 share reservations to exclude inconsistent file access, there is an 3667 analogous set of constraints that apply to client side data caching. 3668 These rules are effective only if the file locking is used in a way 3669 that matches in an equivalent way the actual READ and WRITE 3670 operations executed. This is as opposed to file locking that is 3672 Draft Specification NFS version 4 Protocol February 2000 3674 based on pure convention. For example, it is possible to manipulate 3675 a two-megabyte file by dividing the file into two one-megabyte 3676 regions and protecting access to the two regions by file locks on 3677 bytes zero and one. A lock for write on byte zero of the file would 3678 represent the right to do READ and WRITE operations on the first 3679 region. A lock for write on byte one of the file would represent the 3680 right to do READ and WRITE operations on the second region. As long 3681 as all applications manipulating the file obey this convention, they 3682 will work on a local file system. However, they may not work with 3683 the NFS version 4 protocol unless clients refrain from data caching. 3685 The rules for data caching in the file locking environment are: 3687 o First, when a client obtains a file lock for a particular 3688 region, the data cache corresponding to that region (if any 3689 cache data exists) must be revalidated. If the change attribute 3690 indicates that the file may have been updated since the cached 3691 data was obtained, the client must flush or invalidate the 3692 cached data for the newly locked region. A client might choose 3693 to invalidate all of non-modified cached data that it has for 3694 the file but the only requirement for correct operation is to 3695 invalidate all of the data in the newly locked region. 3697 o Second, before releasing a write lock for a region, all modified 3698 data for that region must be flushed to the server. The 3699 modified data must also be written to stable storage. 3701 Note that flushing data to the server and the invalidation of cached 3702 data must reflect the actual byte ranges locked or unlocked. 3703 Rounding these up or down to reflect client cache block boundaries 3704 will cause problems if not carefully done. For example, writing a 3705 modified block when only half of that block is within an area being 3706 unlocked may cause invalid modification to the region outside the 3707 unlocked area. This, in turn, may be part of a region locked by 3708 another client. Clients can avoid this situation by synchronously 3709 performing portions of write operations that overlap that portion 3710 (initial or final) that is not a full block. Similarly, invalidating 3711 a locked area which is not an integral number of full buffer blocks 3712 would require the client to read one or two partial blocks from the 3713 server if the revalidation procedure shows that the data which the 3714 client possesses may not be valid. 3716 The data that is written to the server as a pre-requisite to the 3717 unlocking of a region must be written to stable storage. The client 3718 may accomplish this either with synchronous writes or by following 3719 asynchronous writes with a COMMIT operation. This is required 3720 because retransmission of the modified data after a server reboot 3721 might conflict with a lock held by another client. 3723 Draft Specification NFS version 4 Protocol February 2000 3725 A client implementation may choose to accommodate applications which 3726 use record locking in non-standard ways (e.g. using a record lock as 3727 a global semaphore) by flushing to the server more data upon an LOCKU 3728 than is covered by the locked range. This may include modified data 3729 within files other than the one for which the unlocks are being done. 3730 In such cases, the client must not interfere with applications whose 3731 READs and WRITEs are being done only within the bounds of record 3732 locks which the application holds. For example, an application locks 3733 a single byte of a file and proceeds to write that single byte. A 3734 client that chose to handle a LOCKU by flushing all modified data to 3735 the server could validly write that single byte in response to an 3736 unrelated unlock. However, it would not be valid to write the entire 3737 block in which that single written byte was located since it includes 3738 an area that is not locked and might be locked by another client. 3739 Client implementations can avoid this problem by dividing files with 3740 modified data into those for which all modifications are done to 3741 areas covered by an appropriate record lock and those for which there 3742 are modifications not covered by a record lock. Any writes done for 3743 the former class of files must not include areas not locked and thus 3744 not modified on the client. 3746 9.3.3. Data Caching and Mandatory File Locking 3748 Client side data caching needs to respect mandatory file locking when 3749 it is in effect. The presence of mandatory file locking for a given 3750 file is indicated in the result flags for an OPEN. When mandatory 3751 locking is in effect for a file, the client must check for an 3752 appropriate file lock for data being read or written. If a lock 3753 exists for the range being read or written, the client may satisfy 3754 the request using the client's validated cache. If an appropriate 3755 file lock is not held for the range of the read or write, the read or 3756 write request must not be satisfied by the client's cache and the 3757 request sent to the server for processing. When a read or write 3758 request partially overlaps a locked region, the request should be 3759 subdivided into multiple pieces with each region (locked or not) 3760 treated appropriately. 3762 9.3.4. Data Caching and File Identity 3764 When clients cache data, the file data needs to organized according 3765 to the file system object to which the data belongs. For NFS version 3766 3 clients, the typical practice has been to assume for the purpose of 3767 caching that distinct filehandles represent distinct file system 3768 objects. The client then has the choice to organize and maintain the 3769 data cache on this basis. 3771 Draft Specification NFS version 4 Protocol February 2000 3773 In the NFS version 4 protocol, there is now the possibility to have 3774 significant deviations from a "one filehandle per object" model 3775 because a filehandle may be constructed on the basis of the object's 3776 pathname. Therefore, clients need a reliable method to determine if 3777 two filehandles designate the same file system object. If clients 3778 were simply to assume that all distinct filehandles denote distinct 3779 objects and proceed to do data caching on this basis, caching 3780 inconsistencies would arise between the distinct client side objects 3781 which mapped to the same server side object. 3783 By providing a method to differentiate filehandles, the NFS version 4 3784 protocol alleviates a potential functional regression in comparison 3785 with the NFS version 3 protocol. Without this method, caching 3786 inconsistencies within the same client could occur and this has not 3787 been present in previous versions of the NFS protocol. Note that it 3788 is possible to have such inconsistencies with applications executing 3789 on multiple clients but that is not the issue being addressed here. 3791 For the purposes of data caching, the following steps allow an NFS 3792 version 4 client to determine whether two distinct filehandles denote 3793 the same server side object: 3795 o If GETATTR directed to two filehandles have different values of 3796 the fsid attribute, then the filehandles represent distinct 3797 objects. 3799 o If GETATTR for any file with an fsid that matches the fsid of 3800 the two filehandles in question returns a unique_handles 3801 attribute with a value of TRUE, then the two objects are 3802 distinct. 3804 o If GETATTR directed to the two filehandles does not return the 3805 fileid attribute for one or both of the handles, then the it 3806 cannot be determined whether the two objects are the same. 3807 Therefore, operations which depend on that knowledge (e.g. 3808 client side data caching) cannot be done reliably. 3810 o If GETATTR directed to the two filehandles returns different 3811 values for the fileid attribute, then they are distinct objects. 3813 o Otherwise they are the same object. 3815 9.4. Open Delegation 3817 When a file is being OPENed, the server may delegate further handling 3818 of opens and closes for that file to the opening client. Any such 3820 Draft Specification NFS version 4 Protocol February 2000 3822 delegation is recallable, since the circumstances that allowed for 3823 the delegation are subject to change. In particular, the server may 3824 receive a conflicting OPEN from another client, the server must 3825 recall the delegation before deciding whether the OPEN from the other 3826 client may be granted. Making a delegation is up to the server and 3827 clients should not assume that any particular OPEN either will or 3828 will not result in an open delegation. The following is a typical 3829 set of conditions that servers might use in deciding whether OPEN 3830 should be delegated: 3832 o The client must be able to respond to the server's callback 3833 requests. The server will use the CB_NULL procedure for a test 3834 of callback ability. 3836 o The client must have responded properly to previous recalls. 3838 o There must be no current open conflicting with the requested 3839 delegation. 3841 o There should be no current delegation that conflicts with the 3842 delegation being requested. 3844 o The probability of future conflicting open requests should be 3845 low based on the recent history of the file. 3847 o The existence of any server-specific semantics of OPEN/CLOSE 3848 that would make the required handling incompatible with the 3849 prescribed handling that the delegated client would apply (see 3850 below). 3852 There are two types of open delegations, read and write. A read open 3853 delegation allows a client to handle, on its own, requests to open a 3854 file for reading that do not deny read access to others. Multiple 3855 read open delegations may be outstanding simultaneously and do not 3856 conflict. A write open delegation allows the client to handle, on 3857 its own, all opens. Only one write open delegation may exist for a 3858 given file at a given time and it is inconsistent with any read open 3859 delegations. 3861 When a client has a read open delegation, it may not make any changes 3862 to the contents or attributes of the file but it is assured that no 3863 other client may do so. When a client has a write open delegation, 3864 it may modify the file data since no other client will be accessing 3865 the file's data. The client holding a write delegation may only 3866 affect file attributes which are intimately connected with the file 3867 data: object_size, time_modify, change. 3869 When a client has an open delegation, it does not send OPENs or 3871 Draft Specification NFS version 4 Protocol February 2000 3873 CLOSEs to the server but updates the appropriate status internally. 3874 For a read open delegation, opens that cannot be handled locally 3875 (opens for write or that deny read access) must be sent to the 3876 server. 3878 When an open delegation is made, the response to the OPEN contains an 3879 open delegation structure which specifies the following: 3881 o the type of delegation (read or write) 3883 o space limitation information to control flushing of data on 3884 close (write open delegation only, see the section "Open 3885 Delegation and Data Caching") 3887 o an nfsace4 specifying read and write permissions 3889 o a stateid to represent the delegation for READ and WRITE 3891 The stateid is separate and distinct from the stateid for the OPEN 3892 proper. The standard stateid, unlike the delegation stateid, is 3893 associated with a particular nfs_lockowner and will continue to be 3894 valid after the delegation is recalled and the file remains open. 3896 When a request internal to the client is made to open a file and open 3897 delegation is in effect, it will be accepted or rejected solely on 3898 the basis of the following conditions. Any requirement for other 3899 checks to be made by the delegate should result in open delegation 3900 being denied so that the checks can be made by the server itself. 3902 o The access and deny bits for the request and the file as 3903 described in the section "Share Reservations". 3905 o The read and write permissions as determined below. 3907 The nfsace4 passed with delegation can be used to avoid frequent 3908 ACCESS calls. The permission check should be as follows: 3910 o If the nfsace4 indicates that the open may be done, then it 3911 should be granted without reference to the server. 3913 o If the nfsace4 indicates that the open may not be done, then an 3914 ACCESS request must be sent to the server to obtain the 3915 definitive answer. 3917 The server may return an nfsace4 that is more restrictive than the 3918 actual ACL of the file. This includes an nfsace4 that specifies 3919 denial of all access. Note that some common practices such as 3921 Draft Specification NFS version 4 Protocol February 2000 3923 mapping the traditional user "root" to the user "nobody" may make it 3924 incorrect to return the actual ACL of the file in the delegation 3925 response. 3927 The use of delegation together with various other forms of caching 3928 creates the possibility that no server authentication will ever be 3929 performed for a given user since all of the user's requests might be 3930 satisfied locally. Where the client is depending on the server for 3931 authentication, the client should be sure authentication occurs for 3932 each user by use of the ACCESS operation. This should be the case 3933 even if an ACCESS operation would not be required otherwise. As 3934 mentioned before, the server may enforce frequent authentication by 3935 returning an nfsace4 denying all access with every open delegation. 3937 9.4.1. Open Delegation and Data Caching 3939 OPEN delegation allows much of the message overhead associated with 3940 the opening and closing files to be eliminated. An open when an open 3941 delegation is in effect does not require that a validation message be 3942 sent to the server. The continued endurance of the "read open 3943 delegation" provides a guarantee that no OPEN for write and thus no 3944 write has occurred. Similarly, when closing a file opened for write 3945 and if write open delegation is in effect, the data written does not 3946 have to be flushed to the server until the open delegation is 3947 recalled. The continued endurance of the open delegation provides a 3948 guarantee that no open and thus no read or write has been done by 3949 another client. 3951 For the purposes of open delegation, READs and WRITEs done without an 3952 OPEN are treated as the functional equivalents of a corresponding 3953 type of OPEN. This refers to the READs and WRITEs that use the 3954 special stateids consisting of all zero bits or all one bits. 3955 Therefore, READs or WRITEs with a special stateid done by another 3956 client will force the server to recall a write open delegation. A 3957 WRITE with a special stateid done by another client will force a 3958 recall of read open delegations. 3960 With delegations, a client is able to avoid writing data to the 3961 server when the CLOSE of a file is serviced. The CLOSE operation is 3962 the usual point at which the client is notified of a lack of stable 3963 storage for the modified file data generated by the application. At 3964 the CLOSE, file data is written to the server and through normal 3965 accounting the server is able to determine if the available file 3966 system space for the data has been exceeded (i.e. server returns 3967 NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. 3968 The introduction of delegations requires that a alternative method be 3969 in place for the same type of communication to occur between client 3971 Draft Specification NFS version 4 Protocol February 2000 3973 and server. 3975 In the delegation response, the server provides either the limit of 3976 the size of the file or the number of modified blocks and associated 3977 block size. The server must ensure that the client will be able to 3978 flush data to the server of a size equal to that provided in the 3979 original delegation. The server must make this assurance for all 3980 outstanding delegations. Therefore, the server must be careful in 3981 its management of available space for new or modified data taking 3982 into account available file system space and any applicable quotas. 3983 The server can recall delegations as a result of managing the 3984 available file system space. The client should abide by the server's 3985 state space limits for delegations. If the client exceeds the stated 3986 limits for the delegation, the server's behavior is undefined. 3988 Based on server conditions, quotas or available file system space, 3989 the server may grant write open delegations with very restrictive 3990 space limitations. The limitations may be defined in a way that will 3991 always force modified data to be flushed to the server on close. 3993 With respect to authentication, flushing modified data to the server 3994 after a CLOSE has occurred may be problematic. For example, the user 3995 of the application may have logged off of the client and unexpired 3996 authentication credentials may not be present. In this case, the 3997 client may need to take special care to ensure that local unexpired 3998 credentials will in fact be available. This may be accomplished by 3999 tracking the expiration time of credentials and flushing data well in 4000 advance of their expiration or by making private copies of 4001 credentials to assure their availability when needed. 4003 9.4.2. Open Delegation and File Locks 4005 When a client holds a write open delegation, lock operations are 4006 performed locally. This includes those required for mandatory file 4007 locking. This can be done since the delegation implies that there 4008 can be no conflicting locks. Similarly, all of the revalidations 4009 that would normally be associated with obtaining locks and the 4010 flushing of data associated with the releasing of locks need not be 4011 done. 4013 9.4.3. Recall of Open Delegation 4015 The following events necessitate recall of an open delegation: 4017 o Potentially conflicting OPEN request (or READ/WRITE done with 4018 "special" stateid) 4020 Draft Specification NFS version 4 Protocol February 2000 4022 o SETATTR issued by another client 4024 o REMOVE request for the file 4026 o RENAME request for the file as either source or target of the 4027 RENAME 4029 Whether a RENAME of a directory in the path leading to the file 4030 results in recall of an open delegation depends on the semantics of 4031 the server file system. If that file system denies such RENAMEs when 4032 a file is open, the recall must be performed to determine whether the 4033 file in question is, in fact, open. 4035 In addition to the situations above, the server may choose to recall 4036 open delegations at any time if resource constraints make it 4037 advisable to do so. Clients should always be prepared for the 4038 possibility of recall. 4040 The server needs to employ special handling for a GETATTR where the 4041 target is a file that has a write open delegation in effect. In this 4042 case, the client holding the delegation needs to be interrogated. 4043 The server will use a CB_GETATTR callback, if the GETATTR attribute 4044 bits include any of the attributes that a write open delegate may 4045 modify (object_size, time_modify, change). 4047 When a client receives a recall for an open delegation, it needs to 4048 update state on the server before returning the delegation. These 4049 same updates must be done whenever a client chooses to return a 4050 delegation voluntarily. The following items of state need to be 4051 dealt with: 4053 o If the file associated with the delegation is no longer open and 4054 no previous CLOSE operation has been sent to the server, a CLOSE 4055 operation must be sent to the server. 4057 o If file has other open references at the client, then OPEN 4058 operations must be sent to the server. The appropriate stateids 4059 will be provided by the server for subsequent use by the client 4060 since the delegation stateid will not longer be valid. These 4061 OPEN requests are done with the claim type of 4062 CLAIM_DELEGATE_CUR. This will allow the presentation of the 4063 delegation stateid so that the client can establish the 4064 appropriate rights to perform the OPEN. (see the section 4065 "Operation 18: OPEN" for details.) 4067 o If there are granted file locks, the corresponding LOCK 4068 operations need to be performed. This applies to the write open 4069 delegation case only. 4071 Draft Specification NFS version 4 Protocol February 2000 4073 o For a write open delegation, if, at the time of recall, if the 4074 file is not open for write, all modified data for the file must 4075 be flushed to the server. If the delegation had not existed, 4076 the client would have done this data flush before the CLOSE 4077 operation. 4079 o With the write open delegation in place, it is possible that the 4080 file was truncated during the duration of the delegation. For 4081 example, the truncation could have occurred as a result of an 4082 OPEN UNCHECKED with a object_size attribute value of zero. 4083 Therefore, if a truncation of the file has occurred and this 4084 operation has not been propagated to the server, the truncation 4085 must occur before any modified data is written to the server. 4087 o Any modified data for the file needs to be flushed to the the 4088 server. 4090 In the case of write open delegation, file locking imposes some 4091 additional requirements. The flushing of any modified data in any 4092 region for which a write lock was released while the write open 4093 delegation was in effect is what is required to precisely maintain 4094 the associated invariant. However, because the write open delegation 4095 implies no other locking by other clients, a simpler implementation 4096 is to flush all modified data for the file (as described just above) 4097 if any write lock has been released while the write open delegation 4098 was in effect. 4100 9.4.4. Delegation Revocation 4102 At the point a delegation is revoked, if there are associated opens 4103 on the client, the applications holding these opens need to be 4104 notified. This notification usually occurs by returning errors for 4105 READ/WRITE operations or when a close is attempted for the open file. 4107 If no opens exist for the file at the point the delegation is 4108 revoked, then notification of the revocation is unnecessary. 4109 However, if there is modified data present at the client for the 4110 file, the user of the application should be notified. Unfortunately, 4111 it may not be possible to notify the user since active applications 4112 may not be present at the client. See the section "Revocation 4113 Recovery for Write Open Delegation" for additional details. 4115 9.5. Data Caching and Revocation 4117 When locks and delegations are revoked, the assumptions upon which 4118 successful caching depend are no longer guaranteed. The owner of the 4120 Draft Specification NFS version 4 Protocol February 2000 4122 locks or share reservations which have been revoked needs to be 4123 notified. This notification includes applications with a file open 4124 that has a corresponding delegation which has been revoked. Cached 4125 data associated with the revocation must be removed from the client. 4126 In the case of modified data existing in the client's cache, that 4127 data must be removed from the client without it being written to the 4128 server. 4130 Notification to a lock owner will in many cases consist of simply 4131 returning an error on the next and all subsequent READs/WRITEs to the 4132 open file or on the close. Where the methods available to a client 4133 to make such notification impossible because errors for certain 4134 operations may not be returned, more drastic action such as signals 4135 or process termination may be appropriate. The justification for 4136 this is that an invariant for which an application depends on may be 4137 violated. Depending on how errors are typically treated for the 4138 client operating environment, further levels of notification 4139 including logging, console messages, and GUI pop-ups may be 4140 appropriate. 4142 9.5.1. Revocation Recovery for Write Open Delegation 4144 Revocation recovery for a write open delegation poses the special 4145 issue of modified data in the client cache while the file is not 4146 open. In this situation, any client which does not flush modified 4147 data to the server on each close must ensure that the user receives 4148 appropriate notification of the failure as a result of the 4149 revocation. Since such situations may require human action to 4150 correct problems, notification schemes in which the appropriate user 4151 or administrator is notified may be necessary. Logging and console 4152 messages are typical examples. 4154 If there is modified data on the client, it must not be flushed 4155 normally to the server. A client may attempt to provide a copy of 4156 the file data as modified during the delegation under a different 4157 name in the file system name space to ease recovery. Unless the 4158 client can determine that the file has not modified by any other 4159 client, this technique must be limited to situations in which a 4160 client has a complete cached copy of the file in question. Use of 4161 such a technique may be limited to files under a certain size or may 4162 only be used when sufficient disk space is guaranteed to be available 4163 within the target file system and when the client has sufficient 4164 buffering resources to keep the cached copy available until it is 4165 properly stored to the target file system. 4167 Draft Specification NFS version 4 Protocol February 2000 4169 9.6. Attribute Caching 4171 The attributes discussed in this section do not include named 4172 attributes. Individual named attributes are analogous to files and 4173 caching of the data for these needs to be handled just as data 4174 caching is for ordinary files. Similarly, LOOKUP results from an 4175 OPENATTR directory are to be cached on the same basis as any other 4176 pathnames and similarly for directory contents. 4178 Clients may cache file attributes obtained from the server and use 4179 them to avoid subsequent GETATTR requests. Such caching is write 4180 through in that modification to file attributes is always done by 4181 means of requests to the server and should not be done locally and 4182 cached. The exception to this are modifications to attributes that 4183 are intimately connected with data caching. Therefore, extending a 4184 file by writing data to the local data cache is reflected immediately 4185 in the object_size as seen on the client without this change being 4186 immediately reflected on the server. Normally such changes are not 4187 propagated directly to the server but when the modified data is 4188 flushed to the server, analogous attribute changes are made on the 4189 server. When open delegation is in effect, the modified attributes 4190 may be returned to the server in the response to a CB_RECALL call. 4192 The result of local caching of attributes is that the attribute 4193 caches maintained on individual clients will not be coherent. Changes 4194 made in one order on the server may be seen in a different order on 4195 one client and in a third order on a different client. 4197 The typical file system application programming interfaces do not 4198 provide means to atomically modify or interrogate attributes for 4199 multiple files at the same time. The following rules provide an 4200 environment where the potential incoherences mentioned above can be 4201 reasonably managed. These rules are derived from the practice of 4202 previous NFS protocols. 4204 o All attributes for a given file (per-fsid attributes excepted) 4205 are cached as a unit at the client so that no non- 4206 serializability can arise within the context of a single file. 4208 o An upper time boundary is maintained on how long a client cache 4209 entry can be kept without being refreshed from the server. 4211 o When operations are performed that change attributes at the 4212 server, the updated attribute set is requested as part of the 4213 containing RPC. This includes directory operations that update 4214 attributes indirectly. This is accomplished by following the 4215 modifying operation with a GETATTR operation and then using the 4216 results of the GETATTR to update the client's cached attributes. 4218 Draft Specification NFS version 4 Protocol February 2000 4220 Note that if the full set of attributes to be cached is requested by 4221 READDIR, the results can be cached by the client on the same basis as 4222 attributes obtained via GETATTR. 4224 A client may validate its cached version of attributes for a file by 4225 fetching only the change attribute and assuming that if the change 4226 attribute has the same value as it did when the attributes were 4227 cached, then no attributes have changed. The possible exception is 4228 the attribute time_access. 4230 9.7. Name Caching 4232 The results of LOOKUP and READDIR operations may be cached to avoid 4233 the cost of subsequent LOOKUP operations. Just as in the case of 4234 attribute caching, inconsistencies may arise among the various client 4235 caches. To mitigate the effects of these inconsistencies and given 4236 the context of typical file system APIs, the following rules should 4237 be followed: 4239 o The results of unsuccessful LOOKUPs should not be cached, unless 4240 they are specifically reverified at the point of use. 4242 o An upper time boundary is maintained on how long a client name 4243 cache entry can be kept without verifying that the entry has not 4244 been made invalid by a directory change operation performed by 4245 another client. 4247 When a client is not making changes to a directory for which there 4248 exist name cache entries, the client needs to periodically fetch 4249 attributes for that directory to ensure that it is not being 4250 modified. After determining that no modification has occurred, the 4251 expiration time for the associated name cache entries may be updated 4252 to be the current time plus the name cache staleness bound. 4254 When a client is making changes to a given directory, it needs to 4255 determine whether there have been changes made to the directory by 4256 other clients. It does this by using the change attribute as 4257 reported before and after the directory operation in the associated 4258 change_info4 value returned for the operation. The server is able to 4259 communicate to the client whether the change_info4 data is provided 4260 atomically with respect to the directory operation. If the change 4261 values are provided atomically, the client is then able to compare 4262 the pre-operation change value with the change value in the client's 4263 name cache. If the comparison indicates that the directory was 4264 updated by another client, the name cache associated with the 4265 modified directory is purged from the client. If the comparison 4266 indicates no modification, the name cache can be updated on the 4268 Draft Specification NFS version 4 Protocol February 2000 4270 client to reflect the directory operation and the associated timeout 4271 extended. The post-operation change value needs to be saved as the 4272 basis for future change_info4 comparisons. 4274 As demonstrated by the scenario above, name caching requires that the 4275 client revalidate name cache data by inspecting the change attribute 4276 of a directory at the point when the name cache item was cached. 4277 This requires that the server update the change attribute for 4278 directories when the contents of the corresponding directory is 4279 modified. For a client to use the change_info4 information 4280 appropriately and correctly, the server must report the pre and post 4281 operation change attribute values atomically. When the server is 4282 unable to report the before and after values atomically with respect 4283 to the directory operation, the server must indicate that fact in the 4284 change_info4 return value. When the information is not atomically 4285 reported, the client should not assume that other clients have not 4286 changed the directory. 4288 9.8. Directory Caching 4290 The results of READDIR operations may be used to avoid subsequent 4291 READDIR operations. Just as in the cases of attribute and name 4292 caching inconsistencies may arise among the various client caches. 4293 To mitigate the effects of these inconsistencies and given the 4294 context of typical file system APIs, the following rules should be 4295 followed: 4297 o Cached READDIR information for a directory which is not obtained 4298 in a single READDIR operation must always be a consistent 4299 snapshot of directory contents. This is determined by using a 4300 GETATTR before the first READDIR and after the last of READDIR 4301 that contributes to the cache. 4303 o An upper time boundary is maintained to indicate the length of 4304 time a directory cache entry is considered valid before the 4305 client must revalidate the cached information. 4307 The revalidation technique parallels that discussed in the case of 4308 name caching. When the client is not changing the directory in 4309 question, checking the change attribute of the directory with GETATTR 4310 is adequate. The lifetime of the cache entry can be extended at 4311 these checkpoints. When a client is modifying the directory, the 4312 client needs to use the change_info4 data to determine whether there 4313 are other clients modifying the directory. If it is determined that 4314 no other client modifications are occurring, the client may update 4315 its directory cache to reflect its own changes. 4317 Draft Specification NFS version 4 Protocol February 2000 4319 As demonstrated previously, directory caching requires that the 4320 client revalidate directory cache data by inspecting the change 4321 attribute of a directory at the point when the directory was cached. 4322 This requires that the server update the change attribute for 4323 directories when the contents of the corresponding directory is 4324 modified. For a client to use the change_info4 information 4325 appropriately and correctly, the server must report the pre and post 4326 operation change attribute values atomically. When the server is 4327 unable to report the before and after values atomically with respect 4328 to the directory operation, the server must indicate that fact in the 4329 change_info4 return value. When the information is not atomically 4330 reported, the client should not assume that other clients have not 4331 changed the directory. 4333 Draft Specification NFS version 4 Protocol February 2000 4335 10. Minor Versioning 4337 To address the requirement of an NFS protocol that can evolve as the 4338 need arises, the NFS version 4 protocol contains the rules and 4339 framework to allow for future minor changes or versioning. 4341 The base assumption with respect to minor versioning is that any 4342 future accepted minor version must follow the IETF process and be 4343 documented in a standards track RFC. Therefore, each minor version 4344 number will correspond to an RFC. Minor version zero of the NFS 4345 version 4 protocol is represented by this RFC. The COMPOUND 4346 procedure will support the encoding of the minor version being 4347 requested by the client. 4349 The following items represent the basic rules for the development of 4350 minor versions. Note that a future minor version may decide to 4351 modify or add to the following rules as part of the minor version 4352 definition. 4354 1 Procedures are not added or deleted 4356 To maintain the general RPC model, NFS version 4 minor versions 4357 will not add or delete procedures from the NFS program. 4359 2 Minor versions may add operations to the COMPOUND and 4360 CB_COMPOUND procedures. 4362 The addition of operations to the COMPOUND and CB_COMPOUND 4363 procedures does not affect the RPC model. 4365 2.1 Minor versions may append attributes to GETATTR4args, bitmap4, 4366 and GETATTR4res. 4368 This allows for the expansion of the attribute model to allow 4369 for future growth or adaptation. 4371 2.2 Minor version X must append any new attributes after the last 4372 documented attribute. 4374 Since attribute results are specified as an opaque array of 4375 per-attribute XDR encoded results, the complexity of adding new 4376 attributes in the midst of the current definitions will be too 4377 burdensome. 4379 Draft Specification NFS version 4 Protocol February 2000 4381 3 Minor versions must not modify the structure of an existing 4382 operation's arguments or results. 4384 Again the complexity of handling multiple structure definitions 4385 for a single operation is too burdensome. New operations should 4386 be added instead of modifying existing structures for a minor 4387 version. 4389 This rule does not preclude the following adaptations in a minor 4390 version. 4392 o adding bits to flag fields such as new attributes to 4393 GETATTR's bitmap4 data type 4395 o adding bits to existing attributes like ACLs that have flag 4396 words 4398 o extending enumerated types (including NFS4ERR_*) with new 4399 values 4401 4 Minor versions may not modify the structure of existing 4402 attributes. 4404 5 Minor versions may not delete operations. 4406 This prevents the potential reuse of a particular operation 4407 "slot" in a future minor version. 4409 6 Minor versions may not delete attributes. 4411 7 Minor versions may not delete flag bits or enumeration values. 4413 8 Minor versions may declare an operation as mandatory to NOT 4414 implement. 4416 Specifying an operation as "mandatory to not implement" is 4417 equivalent to obsoleting an operation. For the client, it means 4418 that the operation should not be sent to the server. For the 4419 server, an NFS error can be returned as opposed to "dropping" 4420 the request as an XDR decode error. This approach allows for 4421 the obsolescence of an operation while maintaining its structure 4422 so that a future minor version can reintroduce the operation. 4424 Draft Specification NFS version 4 Protocol February 2000 4426 8.1 Minor versions may declare attributes mandatory to NOT 4427 implement. 4429 8.2 Minor versions may declare flag bits or enumeration values as 4430 mandatory to NOT implement. 4432 9 Minor versions may downgrade features from mandatory to 4433 recommended, or recommended to optional. 4435 10 Minor versions may upgrade features from optional to recommended 4436 or recommended to mandatory. 4438 11 A client and server that support minor version X must support 4439 minor versions 0 (zero) through X-1 as well. 4441 12 No new features may be introduced as mandatory in a minor 4442 version. 4444 This rule allows for the introduction of new functionality and 4445 forces the use of implementation experience before designating a 4446 feature as mandatory. 4448 13 A client MUST NOT attempt to use a stateid, file handle, or 4449 similar returned object from the COMPOUND procedure with minor 4450 version X for another COMPOUND procedure with minor version Y, 4451 where X != Y. 4453 Draft Specification NFS version 4 Protocol February 2000 4455 11. Internationalization 4457 The primary issue in which NFS needs to deal with 4458 internationalization, or i18n, is with respect to file names and 4459 other strings as used within the protocol. NFS' choice of string 4460 representation must allow reasonable name/string access to clients 4461 which use various languages. The UTF-8 encoding of the UCS as 4462 defined by [ISO10646] allows for this type of access and follows the 4463 policy described in "IETF Policy on Character Sets and Languages", 4464 [RFC2277]. This choice is explained further in the following. 4466 11.1. Universal Versus Local Character Sets 4468 [RFC1345] describes a table of 16 bit characters for many different 4469 languages (the bit encodings match Unicode, though of course RFC1345 4470 is somewhat out of date with respect to current Unicode assignments). 4471 Each character from each language has a unique 16 bit value in the 16 4472 bit character set. Thus this table can be thought of as a universal 4473 character set. [RFC1345] then talks about groupings of subsets of 4474 the entire 16 bit character set into "Charset Tables". For example 4475 one might take all the Greek characters from the 16 bit table (which 4476 are are consecutively allocated), and normalize their offsets to a 4477 table that fits in 7 bits. Thus it is determined that "lower case 4478 alpha" is in the same position as "upper case a" in the US-ASCII 4479 table, and "upper case alpha" is in the same position as "lower case 4480 a" in the US-ASCII table. 4482 These normalized subset character sets can be thought of as "local 4483 character sets", suitable for an operating system locale. 4485 Local character sets are not suitable for the NFS protocol. Consider 4486 someone who creates a file with a name in a Swedish character set. 4487 If someone else later goes to access the file with their locale set 4488 to the Swedish language, then there are no problems. But if someone 4489 in say the US-ASCII locale goes to access the file, the file name 4490 will look very different, because the Swedish characters in the 7 bit 4491 table will now be represented in US-ASCII characters on the display. 4492 It would be preferable to give the US-ASCII user a way to display the 4493 file name using Swedish glyphs. In order to do that, the NFS protocol 4494 would have to include the locale with the file name on each operation 4495 to create a file. 4497 But then what of the situation when there is a path name on the 4498 server like: 4500 /component-1/component-2/component-3 4502 Each component could have been created with a different locale. If 4504 Draft Specification NFS version 4 Protocol February 2000 4506 one issues CREATE with multi-component path name, and if some of the 4507 leading components already exist, what is to be done with the 4508 existing components? Is the current locale attribute replaced with 4509 the user's current one? These types of situations quickly become too 4510 complex when there is an alternate solution. 4512 If the NFS version 4 protocol used a universal 16 bit or 32 bit 4513 character set (or a encoding of a 16 bit or 32 bit character set into 4514 octets), then the server and client need not care if the locale of 4515 the user accessing the file is different than the locale of the user 4516 who created the file. The unique 16 bit or 32 bit encoding of the 4517 character allows for determination of what language the character is 4518 from and also how to display that character on the client. The 4519 server need not know what locales are used. 4521 11.2. Overview of Universal Character Set Standards 4523 The previous section makes a case for using a universal character 4524 set. This section makes the case for using UTF-8 as the specific 4525 universal character set for the NFS version 4 protocol. 4527 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 4528 Unicode, and UCS-*. There are two standards bodies managing 4529 universal code sets: 4531 o ISO/IEC which has the standard 10646-1 4533 o Unicode which has the Unicode standard 4535 Both standards bodies have pledged to track each other's assignments 4536 of character codes. 4538 The following is a brief analysis of the various standards. 4540 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 4541 multi-octet character set called the Universal Character 4542 Set (UCS), which encompasses most of the world's writing 4543 systems." 4545 UCS-2 a two octet per character encoding that addresses the first 4546 2^16 characters of UCS. Currently there are no UCS 4547 characters beyond that range. 4549 UCS-4 a four octet per character encoding that permits the 4550 encoding of up to 2^31 characters. 4552 Draft Specification NFS version 4 Protocol February 2000 4554 UTF UCS transformation format. 4556 UTF-1 Only historical interest; it has been removed from 10646-1 4558 UTF-7 Encodes the entire "repertoire" of UCS "characters using 4559 only octets with the higher order bit clear". [RFC2152] 4560 describes UTF-7. UTF-7 accomplishes this by reserving one 4561 of the 7bit US-ASCII characters as a "shift" character to 4562 indicate non-US-ASCII characters. 4564 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 4565 characters are encoded as before unchanged. Any octet with 4566 the high bit cleared can only mean a US-ASCII character. 4567 The high bit set means that a UCS character is being 4568 encoded. 4570 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 4571 reserved range in UCS-2. 4573 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 4575 Up to the present time, changes in Unicode and amendments 4576 to ISO/IEC 10646 have tracked each other, so that the 4577 character repertoires and code point assignments have 4578 remained in sync. The relevant standardization committees 4579 have committed to maintain this very useful synchronism. 4581 11.3. Difficulties with UCS-4, UCS-2, Unicode 4583 Adapting existing applications, and file systems to multi-octet 4584 schemes like UCS and Unicode can be difficult. A significant amount 4585 of code has been written to process streams of bytes. Also there are 4586 many existing stored objects described with 7 bit or 8 bit 4587 characters. Doubling or quadrupling the bandwidth and storage 4588 requirements seems like an expensive way to accomplish I18N. 4590 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 4591 enough but, according to [Unicode1], 49,194 Unicode characters are 4592 already assigned. According to [Unicode2] there are still more 4593 languages that need to be added. 4595 Draft Specification NFS version 4 Protocol February 2000 4597 11.4. UTF-8 and its solutions 4599 UTF-8 solves problems for NFS that exist with the use of UCS and 4600 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 4601 that will be compact for most users. The encoding table from UCS-4 to 4602 UTF-8, as copied from [RFC2279]: 4604 UCS-4 range (hex.) UTF-8 octet sequence (binary) 4605 0000 0000-0000 007F 0xxxxxxx 4606 0000 0080-0000 07FF 110xxxxx 10xxxxxx 4607 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 4609 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 4610 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4611 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4612 10xxxxxx 4614 See [RFC2279] for precise encoding and decoding rules. Note because 4615 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 4616 for the reserved range between D800 and DFFF. 4618 Note that the 16 bit UCS or Unicode characters require no more than 3 4619 octets to encode into UTF-8 4621 Interestingly, UTF-8 has room to handle characters larger than 31 4622 bits, because the leading octet of form: 4624 1111111x 4626 is not defined. If needed, ISO could either use that octet to 4627 indicate a sequence of an encoded 8 octet character, or perhaps use 4628 11111110 to permit the next octet to indicate an even more expandable 4629 character set. 4631 So using UTF-8 to represent character encodings means never having to 4632 run out of room. 4634 11.5. Normalization 4636 The client and server operating environments may differ in their 4637 policies and operational methods with respect to character 4638 normalization (See [Unicode1] for a discussion of normalization 4639 forms). This difference may also exist between applications on the 4640 same client. This adds to the difficulty of providing a single 4641 normalization policy for the protocol that allows for maximal 4642 interoperability. This issue is similar to the character case issues 4643 where the server may or may not support case insensitive file name 4644 matching and may or may not preserve the character case when storing 4646 Draft Specification NFS version 4 Protocol February 2000 4648 file names. The protocol does not mandate a particular behavior but 4649 allows for the various permutations. 4651 The NFS version 4 protocol does not mandate the use of a particular 4652 normalization form at this time. A later revision of this 4653 specification may specify a particular normalization form. 4654 Therefore, the server and client can expect that they may receive 4655 unnormalized characters within protocol requests and responses. If 4656 the operating environment requires normalization, then the 4657 implementation must normalize the various UTF-8 encoded strings 4658 within the protocol before presenting the information to an 4659 application (at the client) or local file system (at the server). 4661 Draft Specification NFS version 4 Protocol February 2000 4663 12. Error Definitions 4665 NFS error numbers are assigned to failed operations within a compound 4666 request. A compound request contains a number of NFS operations that 4667 have their results encoded in sequence in a compound reply. The 4668 results of successful operations will consist of an NFS4_OK status 4669 followed by the encoded results of the operation. If an NFS 4670 operation fails, an error status will be entered in the reply and the 4671 compound request will be terminated. 4673 A description of each defined error follows: 4675 NFS4_OK Indicates the operation completed successfully. 4677 NFS4ERR_ACCES Permission denied. The caller does not have the 4678 correct permission to perform the requested 4679 operation. Contrast this with NFS4ERR_PERM, 4680 which restricts itself to owner or privileged 4681 user permission failures. 4683 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 4684 internal consistency checks. 4686 NFS4ERR_BADTYPE An attempt was made to create an object of a 4687 type not supported by the server. 4689 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 4691 NFS4ERR_BAD_SEQID The sequence number in a locking request is 4692 neither the next expected number or the last 4693 number processed. 4695 NFS4ERR_BAD_STATEID A stateid generated by the current server 4696 instance, but which does not designate any 4697 locking state (either current or superseded) 4698 for a current lockowner-file pair, was used. 4700 NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a 4701 client id is already in use by another client. 4703 NFS4ERR_DELAY The server initiated the request, but was not 4704 able to complete it in a timely fashion. The 4705 client should wait and then try the request 4706 with a new RPC transaction ID. For example, 4707 this error should be returned from a server 4708 that supports hierarchical storage and receives 4710 Draft Specification NFS version 4 Protocol February 2000 4712 a request to process a file that has been 4713 migrated. In this case, the server should start 4714 the immigration process and respond to client 4715 with this error. This error may also occur 4716 when a necessary delegation recall makes 4717 processing a request in a timely fashion 4718 impossible. 4720 NFS4ERR_DENIED An attempt to lock a file is denied. Since 4721 this may be a temporary condition, the client 4722 is encouraged to retry the lock request until 4723 the lock is accepted. 4725 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The 4726 user's resource limit on the server has been 4727 exceeded. 4729 NFS4ERR_EXIST File exists. The file specified already exists. 4731 NFS4ERR_EXPIRED A lease has expired that is being used in the 4732 current procedure. 4734 NFS4ERR_FBIG File too large. The operation would have caused 4735 a file to grow beyond the server's limit. 4737 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 4738 expired at the server. 4740 NFS4ERR_GRACE The server is in its recovery or grace period 4741 which should match the lease period of the 4742 server. 4744 NFS4ERR_INVAL Invalid argument or unsupported argument for an 4745 operation. Two examples are attempting a 4746 READLINK on an object other than a symbolic 4747 link or attempting to SETATTR a time field on a 4748 server that does not support this operation. 4750 NFS4ERR_IO I/O error. A hard error (for example, a disk 4751 error) occurred while processing the requested 4752 operation. 4754 NFS4ERR_ISDIR Is a directory. The caller specified a 4755 directory in a non-directory operation. 4757 NFS4ERR_LEASE_MOVED A lease being renewed is associated with a file 4758 system that has been migrated to a new server. 4760 Draft Specification NFS version 4 Protocol February 2000 4762 NFS4ERR_LOCKED A read or write operation was attempted on a 4763 locked file. 4765 NFS4ERR_LOCK_RANGE A lock request is operating on a sub-range of a 4766 current lock for the lock owner and the server 4767 does not support this type of request. 4769 NFS4ERR_MINOR_VERS_MISMATCH 4770 The server has received a request that 4771 specifies an unsupported minor version. The 4772 server must return a COMPOUND4res with a zero 4773 length operations result array. 4775 NFS4ERR_MLINK Too many hard links. 4777 NFS4ERR_MOVED The filesystem which contains the current 4778 filehandle object has been relocated or 4779 migrated to another server. The client may 4780 obtain the new filesystem location by obtaining 4781 the "fs_locations" attribute for the current 4782 filehandle. For further discussion, refer to 4783 the section "Filesystem Migration or 4784 Relocation". 4786 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 4788 NFS4ERR_NODEV No such device. 4790 NFS4ERR_NOENT No such file or directory. The file or 4791 directory name specified does not exist. 4793 NFS4ERR_NOFILEHANDLE The logical current file handle value has not 4794 been set properly. This may be a result of a 4795 malformed COMPOUND operation (i.e. no PUTFH or 4796 PUTROOTFH before an operation that requires the 4797 current file handle be set). 4799 NFS4ERR_NOSPC No space left on device. The operation would 4800 have caused the server's file system to exceed 4801 its limit. 4803 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 4804 directory in a directory operation. 4806 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 4807 was not empty. 4809 NFS4ERR_NOTSUPP Operation is not supported. 4811 Draft Specification NFS version 4 Protocol February 2000 4813 NFS4ERR_NOT_SAME This error is returned by the VERIFY operation 4814 to signify that the attributes compared were 4815 not the same as provided in the client's 4816 request. 4818 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 4819 during a SETATTR operation. 4821 NFS4ERR_NXIO I/O error. No such device or address. 4823 NFS4ERR_OLD_STATEID A stateid which designates the locking state 4824 for a lockowner-file at an earlier time was 4825 used. 4827 NFS4ERR_PERM Not owner. The operation was not allowed 4828 because the caller is either not a privileged 4829 user (root) or not the owner of the target of 4830 the operation. 4832 NFS4ERR_READDIR_NOSPC The encoded response to a READDIR request 4833 exceeds the size limit set by the initial 4834 request. 4836 NFS4ERR_RESOURCE For the processing of the COMPOUND procedure, 4837 the server may exhaust available resources and 4838 can not continue processing procedures within 4839 the COMPOUND operation. This error will be 4840 returned from the server in those instances of 4841 resource exhaustion related to the processing 4842 of the COMPOUND procedure. 4844 NFS4ERR_ROFS Read-only file system. A modifying operation 4845 was attempted on a read-only file system. 4847 NFS4ERR_SAME This error is returned by the NVERIFY operation 4848 to signify that the attributes compared were 4849 the same as provided in the client's request. 4851 NFS4ERR_SERVERFAULT An error occurred on the server which does not 4852 map to any of the legal NFS version 4 protocol 4853 error values. The client should translate this 4854 into an appropriate error. UNIX clients may 4855 choose to translate this to EIO. 4857 NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share 4858 reservation has failed because of a share 4859 conflict. 4861 Draft Specification NFS version 4 Protocol February 2000 4863 NFS4ERR_STALE Invalid file handle. The file handle given in 4864 the arguments was invalid. The file referred to 4865 by that file handle no longer exists or access 4866 to it has been revoked. 4868 NFS4ERR_STALE_CLIENTID A clientid not recognized by the server was 4869 used in a locking or SETCLIENTID_CONFIRM 4870 request. 4872 NFS4ERR_STALE_STATEID A stateid generated by an earlier server 4873 instance was used. 4875 NFS4ERR_SYMLINK The current file handle provided for a LOOKUP 4876 is not a directory but a symbolic link. 4878 NFS4ERR_TOOSMALL Buffer or request is too small. 4880 NFS4ERR_WRONGSEC The security mechanism being used by the client 4881 for the procedure does not match the server's 4882 security policy. The client should change the 4883 security mechanism being used and retry the 4884 operation. 4886 NFS4ERR_XDEV Attempt to do a cross-device hard link. 4888 Draft Specification NFS version 4 Protocol February 2000 4890 13. NFS Version 4 Requests 4892 For the NFS version 4 RPC program, there are two traditional RPC 4893 procedures: NULL and COMPOUND. All other functionality is defined as 4894 a set of operations and these operations are defined in normal 4895 XDR/RPC syntax and semantics. However, these operations are 4896 encapsulated within the COMPOUND procedure. This requires that the 4897 client combine one or more of the NFS version 4 operations into a 4898 single request. 4900 The NFS4_CALLBACK program is used to provide server to client 4901 signaling and is constructed in a similar fashion as the NFS version 4902 4 program. The procedures CB_NULL and CB_COMPOUND are defined in the 4903 same way as NULL and COMPOUND are within the NFS program. The 4904 CB_COMPOUND request also encapsulates the remaining operations of the 4905 NFS4_CALLBACK program. There is no predefined RPC program number for 4906 the NFS4_CALLBACK program. It is up to the client to specify a 4907 program number in the "transient" program range. The program and 4908 port number of the NFS4_CALLBACK program are provided by the client 4909 as part of the SETCLIENTID operation and therefore is fixed for the 4910 life of the client instantiation. 4912 13.1. Compound Procedure 4914 The COMPOUND procedure provides the opportunity for better 4915 performance within high latency networks. The client can avoid 4916 cumulative latency of multiple RPCs by combining multiple dependent 4917 operations into a single COMPOUND procedure. A compound operation 4918 may provide for protocol simplification by allowing the client to 4919 combine basic procedures into a single request that is customized for 4920 the client's environment. 4922 The CB_COMPOUND procedure precisely parallels the features of 4923 COMPOUND as described above. 4925 The basics of the COMPOUND procedures construction is: 4927 +-----------+-----------+-----------+-- 4928 | op + args | op + args | op + args | 4929 +-----------+-----------+-----------+-- 4931 and the reply looks like this: 4933 +------------+-----------------------+-----------------------+-- 4934 |last status | status + op + results | status + op + results | 4935 +------------+-----------------------+-----------------------+-- 4937 Draft Specification NFS version 4 Protocol February 2000 4939 13.2. Evaluation of a Compound Request 4941 The server will process the COMPOUND procedure by evaluating each of 4942 the operations within the COMPOUND procedure in order. Each 4943 component operation consists of a 32 bit operation code, followed by 4944 the argument of length determined by the type of operation. The 4945 results of each operation are encoded in sequence into a reply 4946 buffer. The results of each operation are preceded by the opcode and 4947 a status code (normally zero). If an operation results in a non-zero 4948 status code, the status will be encoded and evaluation of the 4949 compound sequence will halt and the reply will be returned. 4951 There are no atomicity requirements for the operations contained 4952 within the COMPOUND procedure. The operations being evaluated as 4953 part of a COMPOUND request may be evaluated simultaneously with other 4954 COMPOUND requests that the server receives. 4956 It is the client's responsibility for recovering from any partially 4957 completed COMPOUND procedure. Partially completed COMPOUND 4958 procedures may occur at any point due to errors such as 4959 NFS4ERR_RESOURCE and NFS4ERR_LONG_DELAY. This may occur even given 4960 an otherwise valid operation string. Further, a server reboot which 4961 occurs in the middle of processing a COMPOUND procedure may leave the 4962 client with the difficult task of determining how far COMPOUND 4963 processing has proceeded. Therefore, the client should avoid overly 4964 complex COMPOUND procedures in the event of the failure of an 4965 operation within the procedure. 4967 Each operation assumes a "current" and "saved" filehandle that is 4968 available as part of the execution context of the compound request. 4969 Operations may set, change, or return the current filehandle. The 4970 "saved" filehandle is used for temporary storage of a filehandle 4971 value and as operands for the RENAME and LINK operations. 4973 13.3. Synchronous Modifying Operations 4975 NFS version 4 operations that modify the file system are synchronous. 4976 When an operation is successfully completed at the server, the client 4977 can depend that any data associated with the request is now on stable 4978 storage. This implies that any previous operations within the same 4979 compound request are also reflected in stable storage. This behavior 4980 enables the client's ability to recover from a partially executed 4981 compound request which may resulted from the failure of the server. 4982 For example, if a compound request contains operations A and B and 4983 the server is unable to send a response to the client, depending on 4984 the progress the server made in servicing the request the result of 4985 both operations may be reflected in stable storage or just operation 4987 Draft Specification NFS version 4 Protocol February 2000 4989 A may be reflected. The server must not have just the results of 4990 operation B in stable storage. 4992 13.4. Operation Values 4994 The operations encoded in the COMPOUND procedure are identified by 4995 operation values. To avoid overlap with the RPC procedure numbers, 4996 operations 0 (zero) and 1 are not defined. Operation 2 is not 4997 defined but reserved for future use with minor versioning. 4999 Draft Specification NFS version 4 Protocol February 2000 5001 14. NFS Version 4 Procedures 5003 14.1. Procedure 0: NULL - No Operation 5005 SYNOPSIS 5007 5009 ARGUMENT 5011 void; 5013 RESULT 5015 void; 5017 DESCRIPTION 5019 Standard NULL procedure. Void argument, void response. This 5020 procedure has no functionality associated with it. Because of this 5021 it is sometimes used to measure the overhead of processing a 5022 service request. Therefore, the server should ensure that no 5023 unnecessary work is done in servicing this procedure. 5025 ERRORS 5027 None. 5029 Draft Specification NFS version 4 Protocol February 2000 5031 14.2. Procedure 1: COMPOUND - Compound Operations 5033 SYNOPSIS 5035 compoundargs -> compoundres 5037 ARGUMENT 5039 union nfs_argop4 switch (nfs_opnum4 argop) { 5040 case : ; 5041 ... 5042 }; 5044 struct COMPOUND4args { 5045 utf8string tag; 5046 uint32_t minorversion; 5047 nfs_argop4 argarray<>; 5048 }; 5050 RESULT 5052 union nfs_resop4 switch (nfs_opnum4 resop){ 5053 case : ; 5054 ... 5055 }; 5057 struct COMPOUND4res { 5058 nfsstat4 status; 5059 utf8string tag; 5060 nfs_resop4 resarray<>; 5061 }; 5063 DESCRIPTION 5065 The COMPOUND procedure is used to combine one or more of the NFS 5066 operations into a single RPC request. The main NFS RPC program has 5067 two main procedures: NULL and COMPOUND. All other operations use 5068 the COMPOUND procedure as a wrapper. 5070 The COMPOUND procedure is used to combine individual operations 5071 into a single RPC request. The server interprets each of the 5072 operations in turn. If an operation is executed by the server and 5073 the status of that operation is NFS4_OK, then the next operation in 5075 Draft Specification NFS version 4 Protocol February 2000 5077 the COMPOUND procedure is executed. The server continues this 5078 process until there are no more operations to be executed or one of 5079 the operations has a status value other than NFS4_OK. 5081 In the processing of the COMPOUND procedure, the server may find 5082 that it does not have the available resources to execute any or all 5083 of the operations within the COMPOUND sequence. In this case, the 5084 error NFS4ERR_RESOURCE will be returned for the particular 5085 operation within the COMPOUND procedure where the resource 5086 exhaustion occurred. This assumes that all previous operations 5087 within the COMPOUND sequence have been evaluated successfully. The 5088 results for all of the evaluated operations must be returned to the 5089 client. 5091 The COMPOUND arguments contain a "minorversion" field. The initial 5092 and default value for this field is 0 (zero). This field will be 5093 used by future minor versions such that the client can communicate 5094 to the server what minor version is being requested. If the server 5095 receives a COMPOUND procedure with a minorversion field value that 5096 it does not support, the server MUST return an error of 5097 NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata array. 5099 Contained within the COMPOUND results is a "status" field. If the 5100 results array length is non-zero, this status must be equivalent to 5101 the status of the last operation that was executed within the 5102 COMPOUND procedure. Therefore, if an operation incurred an error 5103 then the "status" value will be the same error value as is being 5104 returned for the operation that failed. 5106 Note that operations, 0 (zero) and 1 (one) are not defined for the 5107 COMPOUND procedure. If the server receives an operation array with 5108 either of these included, an error of NFS4ERR_NOTSUPP must be 5109 returned. Operation 2 is not defined but reserved for future 5110 definition and use with minor versioning. If the server receives a 5111 operation array that contains operation 2 and the minorversion 5112 field has a value of 0 (zero), an error of NFS4ERR_NOTSUPP is 5113 returned. If an operation array contains an operation 2 and the 5114 minorversion field is non-zero and the server does not support the 5115 minor version, the server returns an error of 5116 NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the 5117 NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other 5118 errors. 5120 IMPLEMENTATION 5122 Note that the definition of the "tag" in both the request and 5124 Draft Specification NFS version 4 Protocol February 2000 5126 response are left to the implementor. It may be used to summarize 5127 the content of the compound request for the benefit of packet 5128 sniffers and engineers debugging implementations. 5130 Since an error of any type may occur after only a portion of the 5131 operations have been evaluated, the client must be prepared to 5132 recover from any failure. If the source of an NFS4ERR_RESOURCE 5133 error was a complex or lengthy set of operations, it is likely that 5134 if the number of operations were reduced the server would be able 5135 to evaluate them successfully. Therefore, the client is 5136 responsible for dealing with this type of complexity in recovery. 5138 ERRORS 5140 All errors defined in the protocol 5142 Draft Specification NFS version 4 Protocol February 2000 5144 14.2.1. Operation 3: ACCESS - Check Access Rights 5146 SYNOPSIS 5148 (cfh), accessreq -> supported, accessrights 5150 ARGUMENT 5152 const ACCESS4_READ = 0x00000001; 5153 const ACCESS4_LOOKUP = 0x00000002; 5154 const ACCESS4_MODIFY = 0x00000004; 5155 const ACCESS4_EXTEND = 0x00000008; 5156 const ACCESS4_DELETE = 0x00000010; 5157 const ACCESS4_EXECUTE = 0x00000020; 5159 struct ACCESS4args { 5160 /* CURRENT_FH: object */ 5161 uint32_t access; 5162 }; 5164 RESULT 5166 struct ACCESS4resok { 5167 uint32_t supported; 5168 uint32_t access; 5169 }; 5171 union ACCESS4res switch (nfsstat4 status) { 5172 case NFS4_OK: 5173 ACCESS4resok resok4; 5174 default: 5175 void; 5176 }; 5178 DESCRIPTION 5180 ACCESS determines the access rights that a user, as identified by 5181 the credentials in the RPC request, has with respect to the file 5182 system object specified by the current filehandle. The client 5183 encodes the set of access rights that are to be checked in the bit 5184 mask "access". The server checks the permissions encoded in the 5185 bit mask. If a status of NFS4_OK is returned, two bit masks are 5186 included in the response. The first, "supported", represents the 5188 Draft Specification NFS version 4 Protocol February 2000 5190 access rights for which the server can verify reliably. The 5191 second, "access", represents the access rights available to the 5192 user for the filehandle provided. On success, the current 5193 filehandle retains its value. 5195 Note that the supported field will contain only as many values as 5196 was originally sent in the arguments. For example, if the client 5197 sends an ACCESS operation with only the ACCESS4_READ value set and 5198 the server supports this value, the server will return only 5199 ACCESS4_READ even if it could have reliably checked other values. 5201 The results of this operation are necessarily advisory in nature. 5202 A return status of NFS4_OK and the appropriate bit set in the bit 5203 mask does not imply that such access will be allowed to the file 5204 system object in the future. This is because access rights can be 5205 revoked by the server at any time. 5207 The following access permissions may be requested: 5209 ACCESS4_READ Read data from file or read a directory. 5211 ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- 5212 directory objects). 5214 ACCESS4_MODIFY Rewrite existing file data or modify existing 5215 directory entries. 5217 ACCESS4_EXTEND Write new data or add directory entries. 5219 ACCESS4_DELETE Delete an existing directory entry (no meaning for 5220 non-directory objects). 5222 ACCESS4_EXECUTE Execute file (no meaning for a directory). 5224 IMPLEMENTATION 5226 In general, it is not sufficient for the client to attempt to 5227 deduce access permissions by inspecting the uid, gid, and mode 5228 fields in the file attributes or by attempting to interpret the 5229 contents of the ACL attribute. This is because the server may 5230 perform uid or gid mapping or enforce additional access control 5231 restrictions. It is also possible that the server may not be in 5232 the same ID space as the client. In these cases (and perhaps 5233 others), the client can not reliably perform an access check with 5234 only current file attributes. 5236 Draft Specification NFS version 4 Protocol February 2000 5238 In the NFS version 2 protocol, the only reliable way to determine 5239 whether an operation was allowed was to try it and see if it 5240 succeeded or failed. Using the ACCESS procedure in the NFS version 5241 4 protocol, the client can ask the server to indicate whether or 5242 not one or more classes of operations are permitted. The ACCESS 5243 operation is provided to allow clients to check before doing a 5244 series of operations. This is useful in operating systems (such as 5245 UNIX) where permission checking is done only when a directory is 5246 opened. The intent is to make the behavior of opening a remote 5247 file more consistent with the behavior of opening a local file. 5249 For the NFS version 4 protocol, the use of the ACCESS procedure 5250 when opening a regular file is deprecated in favor of using OPEN. 5252 The information returned by the server in response to an ACCESS 5253 call is not permanent. It was correct at the exact time that the 5254 server performed the checks, but not necessarily afterwards. The 5255 server can revoke access permission at any time. 5257 The client should use the effective credentials of the user to 5258 build the authentication information in the ACCESS request used to 5259 determine access rights. It is the effective user and group 5260 credentials that are used in subsequent read and write operations. 5262 Many implementations do not directly support the ACCESS_DELETE 5263 permission. Operating systems like UNIX will ignore the 5264 ACCESS_DELETE bit if set on an access request on a non-directory 5265 object. In these systems, delete permission on a file is 5266 determined by the access permissions on the directory in which the 5267 file resides, instead of being determined by the permissions of the 5268 file itself. Therefore, the mask returned enumerating which access 5269 rights can be determined will have the ACCESS_DELETE value set to 5270 0. This indicates to the client that the server was unable to 5271 check that particular access right. The ACCESS_DELETE bit in the 5272 access mask returned will then be ignored by the client. 5274 ERRORS 5276 NFS4ERR_ACCES 5277 NFS4ERR_BADHANDLE 5278 NFS4ERR_DELAY 5279 NFS4ERR_FHEXPIRED 5280 NFS4ERR_IO 5281 NFS4ERR_MOVED 5282 NFS4ERR_NOFILEHANDLE 5283 NFS4ERR_RESOURCE 5284 NFS4ERR_SERVERFAULT 5286 Draft Specification NFS version 4 Protocol February 2000 5288 NFS4ERR_STALE 5289 NFS4ERR_WRONGSEC 5291 Draft Specification NFS version 4 Protocol February 2000 5293 14.2.2. Operation 4: CLOSE - Close File 5295 SYNOPSIS 5297 (cfh), stateid -> stateid 5299 ARGUMENT 5301 struct CLOSE4args { 5302 /* CURRENT_FH: object */ 5303 seqid4 seqid 5304 stateid4 stateid; 5305 }; 5307 RESULT 5309 union CLOSE4res switch (nfsstat4 status) { 5310 case NFS4_OK: 5311 stateid4 stateid; 5312 default: 5313 void; 5314 }; 5316 DESCRIPTION 5318 The CLOSE operation releases share reservations for the file as 5319 specified by the current filehandle. The share reservations and 5320 other state information released at the server as a result of this 5321 CLOSE is only associated with the supplied stateid. The sequence 5322 id provides for the correct ordering. State associated with other 5323 OPENs is not affected. 5325 If record locks are held, the client SHOULD release all locks 5326 before issuing a CLOSE. The server MAY free all outstanding locks 5327 on CLOSE but some servers may not support the CLOSE of a file that 5328 still has record locks held. The server MUST return failure if any 5329 locks would exist after the CLOSE. 5331 On success, the current filehandle retains its value. 5333 IMPLEMENTATION 5335 Draft Specification NFS version 4 Protocol February 2000 5337 ERRORS 5339 NFS4ERR_BADHANDLE 5340 NFS4ERR_BAD_SEQID 5341 NFS4ERR_BAD_STATEID 5342 NFS4ERR_DELAY 5343 NFS4ERR_EXPIRED 5344 NFS4ERR_FHEXPIRED 5345 NFS4ERR_GRACE 5346 NFS4ERR_INVAL 5347 NFS4ERR_LEASE_MOVED 5348 NFS4ERR_MOVED 5349 NFS4ERR_NOFILEHANDLE 5350 NFS4ERR_OLD_STATEID 5351 NFS4ERR_RESOURCE 5352 NFS4ERR_SERVERFAULT 5353 NFS4ERR_STALE 5354 NFS4ERR_STALE_STATEID 5356 Draft Specification NFS version 4 Protocol February 2000 5358 14.2.3. Operation 5: COMMIT - Commit Cached Data 5360 SYNOPSIS 5362 (cfh), offset, count -> verifier 5364 ARGUMENT 5366 struct COMMIT4args { 5367 /* CURRENT_FH: file */ 5368 offset4 offset; 5369 count4 count; 5370 }; 5372 RESULT 5374 struct COMMIT4resok { 5375 verifier4 writeverf; 5376 }; 5378 union COMMIT4res switch (nfsstat4 status) { 5379 case NFS4_OK: 5380 COMMIT4resok resok4; 5381 default: 5382 void; 5383 }; 5385 DESCRIPTION 5387 The COMMIT operation forces or flushes data to stable storage for 5388 the file specified by the current file handle. The flushed data is 5389 that which was previously written with a WRITE operation which had 5390 the stable field set to UNSTABLE4. 5392 The offset specifies the position within the file where the flush 5393 is to begin. An offset value of 0 (zero) means to flush data 5394 starting at the beginning of the file. The count specifies the 5395 number of bytes of data to flush. If count is 0 (zero), a flush 5396 from offset to the end of the file is done. 5398 The server returns a write verifier upon successful completion of 5399 the COMMIT. The write verifier is used by the client to determine 5400 if the server has restarted or rebooted between the initial 5401 WRITE(s) and the COMMIT. The client does this by comparing the 5402 write verifier returned from the initial writes and the verifier 5404 Draft Specification NFS version 4 Protocol February 2000 5406 returned by the COMMIT procedure. The server must vary the value 5407 of the write verifier at each server event or instantiation that 5408 may lead to a loss of uncommitted data. Most commonly this occurs 5409 when the server is rebooted; however, other events at the server 5410 may result in uncommitted data loss as well. 5412 On success, the current filehandle retains its value. 5414 IMPLEMENTATION 5416 The COMMIT procedure is similar in operation and semantics to the 5417 POSIX fsync(2) system call that synchronizes a file's state with 5418 the disk (file data and metadata is flushed to disk or stable 5419 storage). COMMIT performs the same operation for a client, flushing 5420 any unsynchronized data and metadata on the server to the server's 5421 disk or stable storage for the specified file. Like fsync(2), it 5422 may be that there is some modified data or no modified data to 5423 synchronize. The data may have been synchronized by the server's 5424 normal periodic buffer synchronization activity. COMMIT should 5425 return NFS4_OK, unless there has been an unexpected error. 5427 COMMIT differs from fsync(2) in that it is possible for the client 5428 to flush a range of the file (most likely triggered by a buffer- 5429 reclamation scheme on the client before file has been completely 5430 written). 5432 The server implementation of COMMIT is reasonably simple. If the 5433 server receives a full file COMMIT request, that is starting at 5434 offset 0 and count 0, it should do the equivalent of fsync()'ing 5435 the file. Otherwise, it should arrange to have the cached data in 5436 the range specified by offset and count to be flushed to stable 5437 storage. In both cases, any metadata associated with the file must 5438 be flushed to stable storage before returning. It is not an error 5439 for there to be nothing to flush on the server. This means that 5440 the data and metadata that needed to be flushed have already been 5441 flushed or lost during the last server failure. 5443 The client implementation of COMMIT is a little more complex. 5444 There are two reasons for wanting to commit a client buffer to 5445 stable storage. The first is that the client wants to reuse a 5446 buffer. In this case, the offset and count of the buffer are sent 5447 to the server in the COMMIT request. The server then flushes any 5448 cached data based on the offset and count, and flushes any metadata 5449 associated with the file. It then returns the status of the flush 5450 and the write verifier. The other reason for the client to 5451 generate a COMMIT is for a full file flush, such as may be done at 5452 close. In this case, the client would gather all of the buffers 5454 Draft Specification NFS version 4 Protocol February 2000 5456 for this file that contain uncommitted data, do the COMMIT 5457 operation with an offset of 0 and count of 0, and then free all of 5458 those buffers. Any other dirty buffers would be sent to the server 5459 in the normal fashion. 5461 After a buffer is written by the client with the stable parameter 5462 set to UNSTABLE4, the buffer must be considered as modified by the 5463 client until the buffer has either been flushed via a COMMIT 5464 operation or written via a WRITE operation with stable parameter 5465 set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer 5466 from being freed and reused before the data can be flushed to 5467 stable storage on the server. 5469 When a response is returned from either a WRITE or a COMMIT 5470 operation and it contains a write verifier that is different than 5471 previously returned by the server, the client will need to 5472 retransmit all of the buffers containing uncommitted cached data to 5473 the server. How this is to be done is up to the implementor. If 5474 there is only one buffer of interest, then it should probably be 5475 sent back over in a WRITE request with the appropriate stable 5476 parameter. If there is more than one buffer, it might be 5477 worthwhile retransmitting all of the buffers in WRITE requests with 5478 the stable parameter set to UNSTABLE4 and then retransmitting the 5479 COMMIT operation to flush all of the data on the server to stable 5480 storage. The timing of these retransmissions is left to the 5481 implementor. 5483 The above description applies to page-cache-based systems as well 5484 as buffer-cache-based systems. In those systems, the virtual 5485 memory system will need to be modified instead of the buffer cache. 5487 ERRORS 5489 NFS4ERR_ACCES 5490 NFS4ERR_BADHANDLE 5491 NFS4ERR_FHEXPIRED 5492 NFS4ERR_IO 5493 NFS4ERR_LOCKED 5494 NFS4ERR_MOVED 5495 NFS4ERR_NOFILEHANDLE 5496 NFS4ERR_RESOURCE 5497 NFS4ERR_ROFS 5498 NFS4ERR_SERVERFAULT 5499 NFS4ERR_STALE 5500 NFS4ERR_WRONGSEC 5502 Draft Specification NFS version 4 Protocol February 2000 5504 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 5506 SYNOPSIS 5508 (cfh), name, type -> (cfh), change_info 5510 ARGUMENT 5512 union createtype4 switch (nfs_ftype4 type) { 5513 case NF4LNK: 5514 linktext4 linkdata; 5515 case NF4BLK: 5516 case NF4CHR: 5517 specdata4 devdata; 5518 case NF4SOCK: 5519 case NF4FIFO: 5520 case NF4DIR: 5521 void; 5522 }; 5524 struct CREATE4args { 5525 /* CURRENT_FH: directory for creation */ 5526 component4 objname; 5527 createtype4 objtype; 5528 }; 5530 RESULT 5532 struct CREATE4resok { 5533 change_info4 cinfo; 5534 }; 5536 union CREATE4res switch (nfsstat4 status) { 5537 case NFS4_OK: 5538 CREATE4resok resok4; 5539 default: 5540 void; 5541 }; 5543 DESCRIPTION 5545 The CREATE operation creates a non-regular file object in a 5546 directory with a given name. The OPEN procedure MUST be used to 5547 create a regular file. 5549 Draft Specification NFS version 4 Protocol February 2000 5551 The objname specifies the name for the new object. If the objname 5552 has a length of 0 (zero), the error NFS4ERR_INVAL will be returned. 5553 The objtype determines the type of object to be created: directory, 5554 symlink, etc. 5556 If an object of the same name already exists in the directory, the 5557 server will return the error NFS4ERR_EXIST. 5559 For the directory where the new file object was created, the server 5560 returns change_info4 information in cinfo. With the atomic field 5561 of the change_info4 struct, the server will indicate if the before 5562 and after change attributes were obtained atomically with respect 5563 to the file object creation. 5565 If the objname has a length of 0 (zero), or if objname does not 5566 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5567 returned. 5569 The current filehandle is replaced by that of the new object. 5571 IMPLEMENTATION 5573 If the client desires to set attribute values after the create, a 5574 SETATTR operation can be added to the COMPOUND request so that the 5575 appropriate attributes will be set. 5577 ERRORS 5579 NFS4ERR_ACCES 5580 NFS4ERR_BADHANDLE 5581 NFS4ERR_BADTYPE 5582 NFS4ERR_DQUOT 5583 NFS4ERR_EXIST 5584 NFS4ERR_FHEXPIRED 5585 NFS4ERR_INVAL 5586 NFS4ERR_IO 5587 NFS4ERR_MOVED 5588 NFS4ERR_NAMETOOLONG 5589 NFS4ERR_NOFILEHANDLE 5590 NFS4ERR_NOSPC 5591 NFS4ERR_NOTDIR 5592 NFS4ERR_NOTSUPP 5593 NFS4ERR_RESOURCE 5594 NFS4ERR_ROFS 5595 NFS4ERR_SERVERFAULT 5596 NFS4ERR_STALE 5598 Draft Specification NFS version 4 Protocol February 2000 5600 NFS4ERR_WRONGSEC 5602 Draft Specification NFS version 4 Protocol February 2000 5604 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery 5606 SYNOPSIS 5608 clientid -> 5610 ARGUMENT 5612 struct DELEGPURGE4args { 5613 clientid4 clientid; 5614 }; 5616 RESULT 5618 struct DELEGPURGE4res { 5619 nfsstat4 status; 5620 }; 5622 DESCRIPTION 5624 Purges all of the delegations awaiting recovery for a given client. 5625 This is useful for clients which do not commit delegation 5626 information to stable storage to indicate that conflicting requests 5627 need not be delayed by the server awaiting recovery of delegation 5628 information. 5630 This operation should also be used by clients which do have 5631 delegation information on stable storage after doing all of 5632 delegation recovery that is needed. Using DELEGPURGE will prevent 5633 any delegations which were made by the server but were not sent to 5634 the client and committed to stable storage from holding up other 5635 clients making conflicting requests. 5637 ERRORS 5639 NFS4ERR_RESOURCE 5640 NFS4ERR_SERVERFAULT 5641 NFS4ERR_STALE_CLIENTID 5643 Draft Specification NFS version 4 Protocol February 2000 5645 14.2.6. Operation 8: DELEGRETURN - Return Delegation 5647 SYNOPSIS 5649 stateid -> 5651 ARGUMENT 5653 struct DELEGRETURN4args { 5654 stateid4 stateid; 5655 }; 5657 RESULT 5659 struct DELEGRETURN4res { 5660 nfsstat4 status; 5661 }; 5663 DESCRIPTION 5665 Returns the delegation represented by the given stateid. 5667 ERRORS 5669 NFS4ERR_BAD_STATEID 5670 NFS4ERR_OLD_STATEID 5671 NFS4ERR_RESOURCE 5672 NFS4ERR_SERVERFAULT 5673 NFS4ERR_STALE_STATEID 5675 Draft Specification NFS version 4 Protocol February 2000 5677 14.2.7. Operation 9: GETATTR - Get Attributes 5679 SYNOPSIS 5681 (cfh), attrbits -> attrbits, attrvals 5683 ARGUMENT 5685 struct GETATTR4args { 5686 /* CURRENT_FH: directory or file */ 5687 bitmap4 attr_request; 5688 }; 5690 RESULT 5692 struct GETATTR4resok { 5693 fattr4 obj_attributes; 5694 }; 5696 union GETATTR4res switch (nfsstat4 status) { 5697 case NFS4_OK: 5698 GETATTR4resok resok4; 5699 default: 5700 void; 5701 }; 5703 DESCRIPTION 5705 The GETATTR operation will obtain attributes for the file system 5706 object specified by the current filehandle. The client sets a bit 5707 in the bitmap argument for each attribute value that it would like 5708 the server to return. The server returns an attribute bitmap that 5709 indicates the attribute values for which it was able to return, 5710 followed by the attribute values ordered lowest attribute number 5711 first. 5713 The server must return a value for each attribute that the client 5714 requests if the attribute is supported by the server. If the 5715 server does not support an attribute or cannot approximate a useful 5716 value then it must not return the attribute value and must not set 5717 the attribute bit in the result bitmap. The server must return an 5718 error if it supports an attribute but cannot obtain its value. In 5719 that case no attribute values will be returned. 5721 All servers must support the mandatory attributes as specified in 5723 Draft Specification NFS version 4 Protocol February 2000 5725 the section "File Attributes". 5727 On success, the current filehandle retains its value. 5729 IMPLEMENTATION 5731 ERRORS 5733 NFS4ERR_ACCES 5734 NFS4ERR_BADHANDLE 5735 NFS4ERR_DELAY 5736 NFS4ERR_FHEXPIRED 5737 NFS4ERR_INVAL 5738 NFS4ERR_IO 5739 NFS4ERR_MOVED 5740 NFS4ERR_NOFILEHANDLE 5741 NFS4ERR_RESOURCE 5742 NFS4ERR_SERVERFAULT 5743 NFS4ERR_STALE 5744 NFS4ERR_WRONGSEC 5746 Draft Specification NFS version 4 Protocol February 2000 5748 14.2.8. Operation 10: GETFH - Get Current Filehandle 5750 SYNOPSIS 5752 (cfh) -> filehandle 5754 ARGUMENT 5756 /* CURRENT_FH: */ 5757 void; 5759 RESULT 5761 struct GETFH4resok { 5762 nfs_fh4 object; 5763 }; 5765 union GETFH4res switch (nfsstat4 status) { 5766 case NFS4_OK: 5767 GETFH4resok resok4; 5768 default: 5769 void; 5770 }; 5772 DESCRIPTION 5774 This operation returns the current filehandle value. 5776 On success, the current filehandle retains its value. 5778 IMPLEMENTATION 5780 Operations that change the current filehandle like LOOKUP or CREATE 5781 do not automatically return the new filehandle as a result. For 5782 instance, if a client needs to lookup a directory entry and obtain 5783 its filehandle then the following request is needed. 5785 PUTFH (directory filehandle) 5786 LOOKUP (entry name) 5787 GETFH 5789 ERRORS 5791 Draft Specification NFS version 4 Protocol February 2000 5793 NFS4ERR_BADHANDLE 5794 NFS4ERR_FHEXPIRED 5795 NFS4ERR_MOVED 5796 NFS4ERR_NOFILEHANDLE 5797 NFS4ERR_RESOURCE 5798 NFS4ERR_SERVERFAULT 5799 NFS4ERR_STALE 5800 NFS4ERR_WRONGSEC 5802 Draft Specification NFS version 4 Protocol February 2000 5804 14.2.9. Operation 11: LINK - Create Link to a File 5806 SYNOPSIS 5808 (sfh), (cfh), newname -> (cfh), change_info 5810 ARGUMENT 5812 struct LINK4args { 5813 /* SAVED_FH: source object */ 5814 /* CURRENT_FH: target directory */ 5815 component4 newname; 5816 }; 5818 RESULT 5820 struct LINK4resok { 5821 change_info4 cinfo; 5822 }; 5824 union LINK4res switch (nfsstat4 status) { 5825 case NFS4_OK: 5826 LINK4resok resok4; 5827 default: 5828 void; 5829 }; 5831 DESCRIPTION 5833 The LINK operation creates an additional newname for the file 5834 represented by the saved filehandle, as set by the SAVEFH 5835 operation, in the directory represented by the current filehandle. 5836 The existing file and the target directory must reside within the 5837 same file system on the server. On success, the current filehandle 5838 will continue to be the target directory. 5840 For the target directory, the server returns change_info4 5841 information in cinfo. With the atomic field of the change_info4 5842 struct, the server will indicate if the before and after change 5843 attributes were obtained atomically with respect to the link 5844 creation. 5846 If the newname has a length of 0 (zero), or if newname does not 5847 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5848 returned. 5850 Draft Specification NFS version 4 Protocol February 2000 5852 IMPLEMENTATION 5854 Changes to any property of the "hard" linked files are reflected in 5855 all of the linked files. When a link is made to a file, the 5856 attributes for the file should have a value for numlinks that is 5857 one greater than the value before the LINK operation. 5859 The comments under RENAME regarding object and target residing on 5860 the same file system apply here as well. The comments regarding the 5861 target name applies as well. 5863 ERRORS 5865 NFS4ERR_ACCES 5866 NFS4ERR_BADHANDLE 5867 NFS4ERR_DELAY 5868 NFS4ERR_DQUOT 5869 NFS4ERR_EXIST 5870 NFS4ERR_FHEXPIRED 5871 NFS4ERR_INVAL 5872 NFS4ERR_IO 5873 NFS4ERR_MLINK 5874 NFS4ERR_MOVED 5875 NFS4ERR_NAMETOOLONG 5876 NFS4ERR_NOSPC 5877 NFS4ERR_NOTDIR 5878 NFS4ERR_NOTSUPP 5879 NFS4ERR_RESOURCE 5880 NFS4ERR_ROFS 5881 NFS4ERR_SERVERFAULT 5882 NFS4ERR_STALE 5883 NFS4ERR_WRONGSEC 5884 NFS4ERR_XDEV 5886 Draft Specification NFS version 4 Protocol February 2000 5888 14.2.10. Operation 12: LOCK - Create Lock 5890 SYNOPSIS 5892 (cfh) type, seqid, reclaim, owner, offset, length -> stateid, 5893 access 5895 ARGUMENT 5897 enum nfs4_lock_type { 5898 READ_LT = 1, 5899 WRITE_LT = 2, 5900 READW_LT = 3, /* blocking read */ 5901 WRITEW_LT = 4 /* blocking write */ 5902 }; 5904 struct LOCK4args { 5905 /* CURRENT_FH: file */ 5906 nfs_lock_type4 locktype; 5907 seqid4 seqid; 5908 bool reclaim; 5909 stateid4 stateid; 5910 offset4 offset; 5911 length4 length; 5912 }; 5914 RESULT 5916 struct LOCK4denied { 5917 nfs_lockowner4 owner; 5918 offset4 offset; 5919 length4 length; 5920 }; 5922 union LOCK4res switch (nfsstat4 status) { 5923 case NFS4_OK: 5924 stateid4 stateid; 5925 case NFS4ERR_DENIED: 5926 LOCK4denied denied; 5927 default: 5928 void; 5929 }; 5931 DESCRIPTION 5933 Draft Specification NFS version 4 Protocol February 2000 5935 The LOCK operation requests a record lock for the byte range 5936 specified by the offset and length parameters. The lock type is 5937 also specified to be one of the nfs4_lock_types. If this is a 5938 reclaim request, the reclaim parameter will be TRUE; 5940 Bytes in a file may be locked even if those bytes are not currently 5941 allocated to the file. To lock the file from a specific offset 5942 through the end-of-file (no matter how long the file actually is) 5943 use a length field with all bits set to 1 (one). To lock the 5944 entire file, use an offset of 0 (zero) and a length with all bits 5945 set to 1. A length of 0 is reserved and should not be used. 5947 In the case that the lock is denied, the the owner, offset, and 5948 length of the conflicting lock are returned. 5950 On success, the current filehandle retains its value. 5952 IMPLEMENTATION 5954 If the server is unable to determine the exact offset and length of 5955 the conflicting lock, the same offset and length that were provided 5956 in the arguments should be returned in the denied results. The 5957 File Locking section contains a full description of this and the 5958 other file locking operations. 5960 ERRORS 5962 NFS4ERR_ACCES 5963 NFS4ERR_BADHANDLE 5964 NFS4ERR_BAD_SEQID 5965 NFS4ERR_BAD_STATEID 5966 NFS4ERR_DELAY 5967 NFS4ERR_DENIED 5968 NFS4ERR_EXPIRED 5969 NFS4ERR_FHEXPIRED 5970 NFS4ERR_GRACE 5971 NFS4ERR_INVAL 5972 NFS4ERR_ISDIR 5973 NFS4ERR_LEASE_MOVED 5974 NFS4ERR_LOCK_RANGE 5975 NFS4ERR_MOVED 5976 NFS4ERR_NOFILEHANDLE 5977 NFS4ERR_OLD_STATEID 5978 NFS4ERR_RESOURCE 5979 NFS4ERR_SERVERFAULT 5980 NFS4ERR_STALE 5982 Draft Specification NFS version 4 Protocol February 2000 5984 NFS4ERR_STALE_CLIENTID 5985 NFS4ERR_STALE_STATEID 5986 NFS4ERR_WRONGSEC 5988 Draft Specification NFS version 4 Protocol February 2000 5990 14.2.11. Operation 13: LOCKT - Test For Lock 5992 SYNOPSIS 5994 (cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED -> 5995 owner} 5997 ARGUMENT 5999 struct LOCKT4args { 6000 /* CURRENT_FH: file */ 6001 nfs_lock_type4 locktype; 6002 nfs_lockowner4 owner; 6003 offset4 offset; 6004 length4 length; 6005 }; 6007 RESULT 6009 union LOCKT4res switch (nfsstat4 status) { 6010 case NFS4ERR_DENIED: 6011 LOCK4denied denied; 6012 case NFS4_OK: 6013 void; 6014 default: 6015 void; 6016 }; 6018 DESCRIPTION 6020 The LOCKT operation tests the lock as specified in the arguments. 6021 If a conflicting lock exists, the owner, offset, and length of the 6022 conflicting lock are returned; if no lock is held, nothing other 6023 than NFS4_OK is returned. 6025 On success, the current filehandle retains its value. 6027 IMPLEMENTATION 6029 If the server is unable to determine the exact offset and length of 6030 the conflicting lock, the same offset and length that were provided 6031 in the arguments should be returned in the denied results. The 6032 File Locking section contains further discussion of the file 6034 Draft Specification NFS version 4 Protocol February 2000 6036 locking mechanisms. 6038 ERRORS 6040 NFS4ERR_ACCES 6041 NFS4ERR_BADHANDLE 6042 NFS4ERR_DELAY 6043 NFS4ERR_DENIED 6044 NFS4ERR_FHEXPIRED 6045 NFS4ERR_GRACE 6046 NFS4ERR_INVAL 6047 NFS4ERR_ISDIR 6048 NFS4ERR_LEASE_MOVED 6049 NFS4ERR_LOCK_RANGE 6050 NFS4ERR_MOVED 6051 NFS4ERR_NOFILEHANDLE 6052 NFS4ERR_RESOURCE 6053 NFS4ERR_SERVERFAULT 6054 NFS4ERR_STALE 6055 NFS4ERR_STALE_CLIENTID 6056 NFS4ERR_WRONGSEC 6058 Draft Specification NFS version 4 Protocol February 2000 6060 14.2.12. Operation 14: LOCKU - Unlock File 6062 SYNOPSIS 6064 (cfh) type, seqid, stateid, offset, length -> stateid 6066 ARGUMENT 6068 struct LOCKU4args { 6069 /* CURRENT_FH: file */ 6070 nfs_lock_type4 type; 6071 seqid4 seqid; 6072 stateid4 stateid; 6073 offset4 offset; 6074 length4 length; 6075 }; 6077 RESULT 6079 union LOCKU4res switch (nfsstat4 status) { 6080 case NFS4_OK: 6081 stateid4 stateid; 6082 default: 6083 void; 6084 }; 6086 DESCRIPTION 6088 The LOCKU operation unlocks the record lock specified by the 6089 parameters. 6091 On success, the current filehandle retains its value. 6093 IMPLEMENTATION 6095 The File Locking section contains a full description of this and 6096 the other file locking procedures. 6098 ERRORS 6100 NFS4ERR_ACCES 6101 NFS4ERR_BADHANDLE 6102 NFS4ERR_BAD_SEQID 6104 Draft Specification NFS version 4 Protocol February 2000 6106 NFS4ERR_BAD_STATEID 6107 NFS4ERR_EXPIRED 6108 NFS4ERR_FHEXPIRED 6109 NFS4ERR_GRACE 6110 NFS4ERR_INVAL 6111 NFS4ERR_LOCK_RANGE 6112 NFS4ERR_LEASE_MOVED 6113 NFS4ERR_MOVED 6114 NFS4ERR_NOFILEHANDLE 6115 NFS4ERR_OLD_STATEID 6116 NFS4ERR_RESOURCE 6117 NFS4ERR_SERVERFAULT 6118 NFS4ERR_STALE 6119 NFS4ERR_STALE_CLIENTID 6120 NFS4ERR_STALE_STATEID 6122 Draft Specification NFS version 4 Protocol February 2000 6124 14.2.13. Operation 15: LOOKUP - Lookup Filename 6126 SYNOPSIS 6128 (cfh), filenames -> (cfh) 6130 ARGUMENT 6132 struct LOOKUP4args { 6133 /* CURRENT_FH: directory */ 6134 pathname4 path; 6135 }; 6137 RESULT 6139 struct LOOKUP4res { 6140 /* CURRENT_FH: object */ 6141 nfsstat4 status; 6142 }; 6144 DESCRIPTION 6146 This operation LOOKUPs or finds a file system object starting from 6147 the directory specified by the current filehandle. LOOKUP 6148 evaluates the pathname contained in the array of names and obtains 6149 a new current filehandle from the final name. All but the final 6150 name in the list must be the names of directories. 6152 If the pathname cannot be evaluated either because a component does 6153 not exist or because the client does not have permission to 6154 evaluate a component of the path, then an error will be returned 6155 and the current filehandle will be unchanged. 6157 If the path is a zero length array, if any component does not obey 6158 the UTF-8 definition, or if any component in the path is of zero 6159 length, the error NFS4ERR_INVAL will be returned. 6161 IMPLEMENTATION 6163 If the client prefers a partial evaluation of the path then a 6164 sequence of LOOKUP operations can be substituted e.g. 6166 Draft Specification NFS version 4 Protocol February 2000 6168 PUTFH (directory filehandle) 6169 LOOKUP "pub" "foo" "bar" 6170 GETFH 6172 or 6174 PUTFH (directory filehandle) 6175 LOOKUP "pub" 6176 GETFH 6177 LOOKUP "foo" 6178 GETFH 6179 LOOKUP "bar" 6180 GETFH 6182 NFS version 4 servers depart from the semantics of previous NFS 6183 versions in allowing LOOKUP requests to cross mountpoints on the 6184 server. The client can detect a mountpoint crossing by comparing 6185 the fsid attribute of the directory with the fsid attribute of the 6186 directory looked up. If the fsids are different then the new 6187 directory is a server mountpoint. Unix clients that detect a 6188 mountpoint crossing will need to mount the server's filesystem. 6190 Servers that limit NFS access to "shares" or "exported" filesystems 6191 should provide a pseudo-filesystem into which the exported 6192 filesystems can be integrated, so that clients can browse the 6193 server's name space. The clients view of a pseudo filesystem will 6194 be limited to paths that lead to exported filesystems. 6196 Note: previous versions of the protocol assigned special semantics 6197 to the names "." and "..". NFS version 4 assigns no special 6198 semantics to these names. The LOOKUPP operator must be used to 6199 lookup a parent directory. 6201 Note that this procedure does not follow symbolic links. The 6202 client is responsible for all parsing of filenames including 6203 filenames that are modified by symbolic links encountered during 6204 the lookup process. 6206 If the current file handle supplied is not a directory but a 6207 symbolic link, the error NFS4ERR_SYMLINK is returned as the error. 6208 For all other non-directory file types, the error NFS4ERR_NOTDIR is 6209 returned. 6211 ERRORS 6213 NFS4ERR_ACCES 6215 Draft Specification NFS version 4 Protocol February 2000 6217 NFS4ERR_BADHANDLE 6218 NFS4ERR_FHEXPIRED 6219 NFS4ERR_INVAL 6220 NFS4ERR_IO 6221 NFS4ERR_MOVED 6222 NFS4ERR_NAMETOOLONG 6223 NFS4ERR_NOENT 6224 NFS4ERR_NOFILEHANDLE 6225 NFS4ERR_NOTDIR 6226 NFS4ERR_RESOURCE 6227 NFS4ERR_SERVERFAULT 6228 NFS4ERR_STALE 6229 NFS4ERR_SYMLINK 6230 NFS4ERR_WRONGSEC 6232 Draft Specification NFS version 4 Protocol February 2000 6234 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory 6236 SYNOPSIS 6238 (cfh) -> (cfh) 6240 ARGUMENT 6242 /* CURRENT_FH: object */ 6243 void; 6245 RESULT 6247 struct LOOKUPP4res { 6248 /* CURRENT_FH: directory */ 6249 nfsstat4 status; 6250 }; 6252 DESCRIPTION 6254 The current filehandle is assumed to refer to a regular directory 6255 or a named attribute directory. LOOKUPP assigns the filehandle for 6256 its parent directory to be the current filehandle. If there is no 6257 parent directory an NFS4ERR_ENOENT error must be returned. 6258 Therefore, NFS4ERR_ENOENT will be returned by the server when the 6259 current filehandle is at the root or top of the server's file tree. 6261 IMPLEMENTATION 6263 As for LOOKUP, LOOKUPP will also cross mountpoints. 6265 If the current filehandle is not a directory or named attribute 6266 directory, the error NFS4ERR_NOTDIR is returned. 6268 ERRORS 6270 NFS4ERR_ACCES 6271 NFS4ERR_BADHANDLE 6272 NFS4ERR_FHEXPIRED 6273 NFS4ERR_INVAL 6274 NFS4ERR_IO 6275 NFS4ERR_MOVED 6276 NFS4ERR_NOENT 6277 NFS4ERR_NOFILEHANDLE 6279 Draft Specification NFS version 4 Protocol February 2000 6281 NFS4ERR_NOTDIR 6282 NFS4ERR_RESOURCE 6283 NFS4ERR_SERVERFAULT 6284 NFS4ERR_STALE 6285 NFS4ERR_WRONGSEC 6287 Draft Specification NFS version 4 Protocol February 2000 6289 14.2.15. Operation 17: NVERIFY - Verify Difference in Attributes 6291 SYNOPSIS 6293 (cfh), attrbits, attrvals -> - 6295 ARGUMENT 6297 struct NVERIFY4args { 6298 /* CURRENT_FH: object */ 6299 bitmap4 attr_request; 6300 fattr4 obj_attributes; 6301 }; 6303 RESULT 6305 struct NVERIFY4res { 6306 nfsstat4 status; 6307 }; 6309 DESCRIPTION 6311 This operation is used to prefix a sequence of operations to be 6312 performed if one or more attributes have changed on some filesystem 6313 object. If all the attributes match then the error NFS4ERR_SAME 6314 must be returned. 6316 IMPLEMENTATION 6318 This operation is useful as a cache validation operator. If the 6319 object to which the attributes belong has changed then the 6320 following operations may obtain new data associated with that 6321 object. For instance, to check if a file has been changed and 6322 obtain new data if it has: 6324 PUTFH (public) 6325 LOOKUP "pub" "foo" "bar" 6326 NVERIFY attrbits attrs 6327 READ 0 32767 6329 In the case that a recommended attribute is specified in the 6330 NVERIFY operation and the server does not support that attribute 6331 for the file system object, the error NFS4ERR_NOTSUPP is returned 6333 Draft Specification NFS version 4 Protocol February 2000 6335 to the client. 6337 ERRORS 6339 NFS4ERR_ACCES 6340 NFS4ERR_BADHANDLE 6341 NFS4ERR_DELAY 6342 NFS4ERR_FHEXPIRED 6343 NFS4ERR_INVAL 6344 NFS4ERR_IO 6345 NFS4ERR_MOVED 6346 NFS4ERR_NOFILEHANDLE 6347 NFS4ERR_NOTSUPP 6348 NFS4ERR_RESOURCE 6349 NFS4ERR_SAME 6350 NFS4ERR_SERVERFAULT 6351 NFS4ERR_STALE 6352 NFS4ERR_WRONGSEC 6354 Draft Specification NFS version 4 Protocol February 2000 6356 14.2.16. Operation 18: OPEN - Open a Regular File 6358 SYNOPSIS 6360 (cfh), claim, openhow, owner, seqid, access, deny -> (cfh), 6361 stateid, cinfo, rflags, open_confirm, delegation 6363 ARGUMENT 6365 struct OPEN4args { 6366 open_claim4 claim; 6367 openflag4 openhow; 6368 nfs_lockowner4 owner; 6369 seqid4 seqid; 6370 uint32_t share_access; 6371 uint32_t share_deny; 6372 }; 6374 enum createmode4 { 6375 UNCHECKED4 = 0, 6376 GUARDED4 = 1, 6377 EXCLUSIVE4 = 2 6378 }; 6380 union createhow4 switch (createmode4 mode) { 6381 case UNCHECKED4: 6382 case GUARDED4: 6383 fattr4 createattrs; 6384 case EXCLUSIVE4: 6385 verifier4 createverf; 6386 }; 6388 enum opentype4 { 6389 OPEN4_NOCREATE = 0, 6390 OPEN4_CREATE = 1 6391 }; 6393 union openflag4 switch (opentype4 opentype) { 6394 case OPEN4_CREATE: 6395 createhow4 how; 6396 default: 6397 void; 6398 }; 6400 /* Next definitions used for OPEN delegation */ 6401 enum limit_by4 { 6402 NFS_LIMIT_SIZE = 1, 6404 Draft Specification NFS version 4 Protocol February 2000 6406 NFS_LIMIT_BLOCKS = 2 6407 /* others as needed */ 6408 }; 6410 struct nfs_modified_limit4 { 6411 uint32_t num_blocks; 6412 uint32_t bytes_per_block; 6413 }; 6415 union nfs_space_limit4 switch (limit_by4 limitby) { 6416 /* limit specified as file size */ 6417 case NFS_LIMIT_SIZE: 6418 uint64_t filesize; 6419 /* limit specified by number of blocks */ 6420 case NFS_LIMIT_BLOCKS: 6421 nfs_modified_limit4 mod_blocks; 6422 } ; 6424 enum open_delegation_type4 { 6425 OPEN_DELEGATE_NONE = 0, 6426 OPEN_DELEGATE_READ = 1, 6427 OPEN_DELEGATE_WRITE = 2 6428 }; 6430 enum open_claim_type4 { 6431 CLAIM_NULL = 0, 6432 CLAIM_PREVIOUS = 1, 6433 CLAIM_DELEGATE_CUR = 2, 6434 CLAIM_DELEGATE_PREV = 3 6435 }; 6437 struct open_claim_delegate_cur4 { 6438 pathname4 file; 6439 stateid4 delegate_stateid; 6440 }; 6442 union open_claim4 switch (open_claim_type4 claim) { 6443 /* 6444 * No special rights to file. Ordinary OPEN of the specified file. 6445 */ 6446 case CLAIM_NULL: 6447 /* CURRENT_FH: directory */ 6448 pathname4 file; 6450 /* 6451 * Right to the file established by an open previous to server 6452 * reboot. File identified by filehandle obtained at that time 6453 * rather than by name. 6455 Draft Specification NFS version 4 Protocol February 2000 6457 */ 6458 case CLAIM_PREVIOUS: 6459 /* CURRENT_FH: file being reclaimed */ 6460 uint32_t delegate_type; 6462 /* 6463 * Right to file based on a delegation granted by the server. 6464 * File is specified by name. 6465 */ 6466 case CLAIM_DELEGATE_CUR: 6467 /* CURRENT_FH: directory */ 6468 open_claim_delegate_cur4 delegate_cur_info; 6470 /* Right to file based on a delegation granted to a previous boot 6471 * instance of the client. File is specified by name. 6472 */ 6473 case CLAIM_DELEGATE_PREV: 6474 /* CURRENT_FH: directory */ 6475 pathname4 file_delegate_prev; 6476 }; 6478 RESULT 6480 struct open_read_delegation4 { 6481 stateid4 stateid; /* Stateid for delegation*/ 6482 bool recall; /* Pre-recalled flag for 6483 delegations obtained 6484 by reclaim 6485 (CLAIM_PREVIOUS) */ 6486 nfsace4 permissions; /* Defines users who don't 6487 need an ACCESS call to 6488 open for read */ 6489 }; 6491 struct open_write_delegation4 { 6492 stateid4 stateid; /* Stateid for delegation 6493 be flushed to the server 6494 on close. */ 6495 bool recall; /* Pre-recalled flag for 6496 delegations obtained 6497 by reclaim 6498 (CLAIM_PREVIOUS) */ 6499 nfs_space_limit4 space_limit; /* Defines condition that 6500 the client must check to 6501 determine whether the 6502 file needs to be flushed 6504 Draft Specification NFS version 4 Protocol February 2000 6506 to the server on close. 6507 */ 6508 nfsace4 permissions; /* Defines users who don't 6509 need an ACCESS call as 6510 part of a delegated 6511 open. */ 6512 }; 6514 union open_delegation4 6515 switch (open_delegation_type4 delegation_type) { 6516 case OPEN_DELEGATE_NONE: 6517 void; 6518 case OPEN_DELEGATE_READ: 6519 open_read_delegation4 read; 6520 case OPEN_DELEGATE_WRITE: 6521 open_write_delegation4 write; 6522 }; 6524 const OPEN4_RESULT_MLOCK = 0x00000001; 6525 const OPEN4_RESULT_CONFIRM= 0x00000002; 6527 struct OPEN4resok { 6528 stateid4 stateid; /* Stateid for open */ 6529 change_info4 cinfo; /* Directory Change Info */ 6530 uint32_t rflags; /* Result flags */ 6531 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 6532 open_delegation4 delegation; /* Info on any open 6533 delegation */ 6534 }; 6536 union OPEN4res switch (nfsstat4 status) { 6537 case NFS4_OK: 6538 /* CURRENT_FH: opened file */ 6539 OPEN4resok result; 6540 default: 6541 void; 6542 }; 6544 DESCRIPTION 6546 The OPEN operation creates and/or opens a regular file in a 6547 directory with the provided name. If the file does not exist at 6548 the server and creation is desired, specification of the method of 6549 creation is provided by the openhow parameter. The client has the 6550 choice of three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE. 6552 UNCHECKED means that the file should be created if a file of that 6554 Draft Specification NFS version 4 Protocol February 2000 6556 name does not exist and encountering an existing regular file of 6557 that name is not an error. For this type of create, createattrs 6558 specifies the initial set of attributes for the file. The set of 6559 attributes may includes any writable attribute valid for regular 6560 files. When an UNCHECKED create encounters an existing file, the 6561 attributes specified by createattrs is not used, except that when 6562 an object_size of zero is specified, the existing file is 6563 truncated. If GUARDED is specified, the server checks for the 6564 presence of a duplicate object by name before performing the 6565 create. If a duplicate exists, an error of NFS4ERR_EXIST is 6566 returned as the status. If the object does not exist, the request 6567 is performed as described for UNCHECKED. 6569 EXCLUSIVE specifies that the server is to follow exclusive creation 6570 semantics, using the verifier to ensure exclusive creation of the 6571 target. The server should check for the presence of a duplicate 6572 object by name. If the object does not exist, the server creates 6573 the object and stores the verifier with the object. If the object 6574 does exist and the stored verifier matches the client provided 6575 verifier, the server uses the existing object as the newly created 6576 object. If the stored verifier does not match, then an error of 6577 NFS4ERR_EXIST is returned. No attributes may be provided in this 6578 case, since the server may use an attribute of the target object to 6579 store the verifier. 6581 For the target directory, the server returns change_info4 6582 information in cinfo. With the atomic field of the change_info4 6583 struct, the server will indicate if the before and after change 6584 attributes were obtained atomically with respect to the link 6585 creation. 6587 Upon successful creation, the current filehandle is replaced by 6588 that of the new object. 6590 The OPEN procedure provides for DOS SHARE capability with the use 6591 of the access and deny fields of the OPEN arguments. The client 6592 specifies at OPEN the required access and deny modes. For clients 6593 that do not directly support SHAREs (i.e. Unix), the expected deny 6594 value is DENY_NONE. In the case that there is a existing SHARE 6595 reservation that conflicts with the OPEN request, the server 6596 returns the error NFS4ERR_DENIED. For a complete SHARE request, 6597 the client must provide values for the owner and seqid fields for 6598 the OPEN argument. For additional discussion of SHARE semantics 6599 see the section on 'Share Reservations'. 6601 In the case that the client is recovering state from a server 6602 failure, the reclaim field of the OPEN argument is used to signify 6603 that the request is meant to reclaim state previously held. 6605 Draft Specification NFS version 4 Protocol February 2000 6607 The "claim" field of the OPEN argument is used to specify the file 6608 to be opened and the state information which the client claims to 6609 possess. There are four basic claim types which cover the various 6610 situations for an OPEN. They are as follows: 6612 CLAIM_NULL 6613 For the client, this is a new OPEN 6614 request and there is no previous state 6615 associate with the file for the client. 6617 CLAIM_PREVIOUS 6618 The client is claiming basic OPEN state 6619 for a file that was held previous to a 6620 server reboot. Generally used when a 6621 server is returning persistent file 6622 handles; the client may not have the 6623 file name to reclaim the OPEN. 6625 CLAIM_DELEGATE_CUR 6626 The client is claiming a delegation for 6627 OPEN as granted by the server. 6628 Generally this is done as part of 6629 recalling a delegation. 6631 CLAIM_DELEGATE_PREV 6632 The client is claiming a delegation 6633 granted to a previous client instance; 6634 used after the client reboots. 6636 For OPEN requests whose claim type is other than CLAIM_PREVIOUS 6637 (i.e. requests other than those devoted to reclaiming opens after a 6638 server reboot) that reach the server during its grace or lease 6639 expiration period, the server returns an error of NFS4ERR_GRACE. 6641 For any OPEN request, the server may return an open delegation, 6642 which allows further opens and closes to be handled locally on the 6643 client as described in the section Open Delegation. Note that 6644 delegation is up to the server to decide. The client should never 6645 assume that delegation will or will not be granted in a particular 6646 instance. It should always be prepared for either case. A partial 6647 exception is the reclaim (CLAIM_PREVIOUS) case, in which a 6648 delegation type is claimed. In this case, delegation will always 6649 be granted, although the server may specify an immediate recall in 6650 the delegation structure. 6652 The rflags returned by a successful OPEN allow the server to return 6653 information governing how the open file is to be handled. 6654 OPEN4_RESULT_MLOCK indicates to the caller that mandatory locking 6655 is in effect for this file and the client should act appropriately 6656 with regard to data cached on the client. OPEN4_RESULT_CONFIRM 6657 indicates that the client MUST execute an OPEN_CONFIRM operation 6659 Draft Specification NFS version 4 Protocol February 2000 6661 before using the open file. 6663 If the file is a zero length array, if any component does not obey 6664 the UTF-8 definition, or if any component in the path is of zero 6665 length, the error NFS4ERR_INVAL will be returned. 6667 When an OPEN is done and the specified lockowner already has the 6668 resulting filehandle open, the result is to "OR" together the new 6669 share and deny status together with the existing status. In this 6670 case, only a single CLOSE need be done, even though multiple OPEN's 6671 were completed. 6673 IMPLEMENTATION 6675 The OPEN procedure contains support for EXCLUSIVE create. The 6676 mechanism is similar to the support in NFS version 3 [RFC1813]. As 6677 in NFS version 3, this mechanism provides reliable exclusive 6678 creation. Exclusive create is invoked when the how parameter is 6679 EXCLUSIVE. In this case, the client provides a verifier that can 6680 reasonably be expected to be unique. A combination of a client 6681 identifier, perhaps the client network address, and a unique number 6682 generated by the client, perhaps the RPC transaction identifier, 6683 may be appropriate. 6685 If the object does not exist, the server creates the object and 6686 stores the verifier in stable storage. For file systems that do not 6687 provide a mechanism for the storage of arbitrary file attributes, 6688 the server may use one or more elements of the object meta-data to 6689 store the verifier. The verifier must be stored in stable storage 6690 to prevent erroneous failure on retransmission of the request. It 6691 is assumed that an exclusive create is being performed because 6692 exclusive semantics are critical to the application. Because of the 6693 expected usage, exclusive CREATE does not rely solely on the 6694 normally volatile duplicate request cache for storage of the 6695 verifier. The duplicate request cache in volatile storage does not 6696 survive a crash and may actually flush on a long network partition, 6697 opening failure windows. In the UNIX local file system 6698 environment, the expected storage location for the verifier on 6699 creation is the meta-data (time stamps) of the object. For this 6700 reason, an exclusive object create may not include initial 6701 attributes because the server would have nowhere to store the 6702 verifier. 6704 If the server can not support these exclusive create semantics, 6705 possibly because of the requirement to commit the verifier to 6706 stable storage, it should fail the OPEN request with the error, 6707 NFS4ERR_NOTSUPP. 6709 Draft Specification NFS version 4 Protocol February 2000 6711 During an exclusive CREATE request, if the object already exists, 6712 the server reconstructs the object's verifier and compares it with 6713 the verifier in the request. If they match, the server treats the 6714 request as a success. The request is presumed to be a duplicate of 6715 an earlier, successful request for which the reply was lost and 6716 that the server duplicate request cache mechanism did not detect. 6717 If the verifiers do not match, the request is rejected with the 6718 status, NFS4ERR_EXIST. 6720 Once the client has performed a successful exclusive create, it 6721 must issue a SETATTR to set the correct object attributes. Until 6722 it does so, it should not rely upon any of the object attributes, 6723 since the server implementation may need to overload object meta- 6724 data to store the verifier. The subsequent SETATTR must not occur 6725 in the same COMPOUND request as the OPEN. This separation will 6726 guarantee that the exclusive create mechanism will continue to 6727 function properly in the face of retransmission of the request. 6729 Use of the GUARDED attribute does not provide exactly-once 6730 semantics. In particular, if a reply is lost and the server does 6731 not detect the retransmission of the request, the procedure can 6732 fail with NFS4ERR_EXIST, even though the create was performed 6733 successfully. 6735 For SHARE reservations, the client must specify a value for access 6736 that is one of READ, WRITE, or BOTH. For deny, the client must 6737 specify one of NONE, READ, WRITE, or BOTH. If the client fails to 6738 do this, the server must return NFS4ERR_INVAL. 6740 ERRORS 6742 NFS4ERR_ACCES 6743 NFS4ERR_BAD_SEQID 6744 NFS4ERR_DELAY 6745 NFS4ERR_DQUOT 6746 NFS4ERR_EXIST 6747 NFS4ERR_FHEXPIRED 6748 NFS4ERR_GRACE 6749 NFS4ERR_IO 6750 NFS4ERR_LEASE_MOVED 6751 NFS4ERR_MOVED 6752 NFS4ERR_NAMETOOLONG 6753 NFS4ERR_NOFILEHANDLE 6754 NFS4ERR_NOSPC 6755 NFS4ERR_NOTDIR 6756 NFS4ERR_NOTSUPP 6757 NFS4ERR_RESOURCE 6759 Draft Specification NFS version 4 Protocol February 2000 6761 NFS4ERR_ROFS 6762 NFS4ERR_SERVERFAULT 6763 NFS4ERR_SHARE_DENIED 6764 NFS4ERR_STALE_CLIENTID 6766 Draft Specification NFS version 4 Protocol February 2000 6768 14.2.17. Operation 19: OPENATTR - Open Named Attribute Directory 6770 SYNOPSIS 6772 (cfh) -> (cfh) 6774 ARGUMENT 6776 /* CURRENT_FH: file or directory */ 6777 void; 6779 RESULT 6781 struct OPENATTR4res { 6782 /* CURRENT_FH: name attr directory*/ 6783 nfsstat4 status; 6784 }; 6786 DESCRIPTION 6788 The OPENATTR operation is used to obtain the filehandle of the 6789 named attribute directory associated with the current filehandle. 6790 The result of the OPENATTR will be a filehandle to an object of 6791 type NF4ATTRDIR. From this filehandle, READDIR and LOOKUP 6792 procedures can be used to obtain filehandles for the various named 6793 attributes associated with the original file system object. 6794 Filehandles returned within the named attribute directory will have 6795 a type of NF4NAMEDATTR. 6797 IMPLEMENTATION 6799 If the server does not support named attributes for the current 6800 filehandle, an error of NFS4ERR_NOTSUPP will be returned to the 6801 client. 6803 ERRORS 6805 NFS4ERR_ACCES 6806 NFS4ERR_BADHANDLE 6807 NFS4ERR_DELAY 6808 NFS4ERR_FHEXPIRED 6809 NFS4ERR_INVAL 6810 NFS4ERR_IO 6812 Draft Specification NFS version 4 Protocol February 2000 6814 NFS4ERR_MOVED 6815 NFS4ERR_NOENT 6816 NFS4ERR_NOFILEHANDLE 6817 NFS4ERR_NOTSUPP 6818 NFS4ERR_RESOURCE 6819 NFS4ERR_SERVERFAULT 6820 NFS4ERR_STALE 6821 NFS4ERR_WRONGSEC 6823 Draft Specification NFS version 4 Protocol February 2000 6825 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open 6827 SYNOPSIS 6829 (cfh), seqid, open_confirm-> stateid 6831 ARGUMENT 6833 struct OPEN_CONFIRM4args { 6834 /* CURRENT_FH: opened file */ 6835 seqid4 seqid; 6836 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 6837 }; 6839 RESULT 6841 struct OPEN_CONFIRM4resok { 6842 stateid4 stateid; 6843 }; 6845 union OPEN_CONFIRM4res switch (nfsstat4 status) { 6846 case NFS4_OK: 6847 OPEN_CONFIRM4resok resok4; 6848 default: 6849 void; 6850 }; 6852 DESCRIPTION 6854 This operation is used to confirm the sequence id usage for the 6855 first time that a nfs_lockowner is used by a client. The OPEN 6856 operation returns a opaque confirmation verifier that is then 6857 passed to this operation along with the next sequence id for the 6858 nfs_lockowner. The sequence id passed to the OPEN_CONFIRM must be 6859 1 (one) greater than the seqid passed to the OPEN operation from 6860 which the open_confirm value was obtained. If the server receives 6861 an unexpected sequence id with respect to the original open, then 6862 the server assumes that the client will not confirm the original 6863 OPEN and all state associated with the original OPEN is released by 6864 the server. 6866 On success, the current filehandle retains its value. 6868 IMPLEMENTATION 6870 Draft Specification NFS version 4 Protocol February 2000 6872 A given client might generate many nfs_lockowner data structures 6873 for a given clientid. The client will periodically either dispose 6874 of its nfs_lockowners or stop using them for indefinite periods of 6875 time. The latter situation is why the NFS version 4 protocol does 6876 not have a an explicit operation to exit an nfs_lockowner: such an 6877 operation is of no use in that situation. Instead, to avoid 6878 unbounded memory use, the server needs to implement a strategy for 6879 disposing of nfs_lockowners that have no current lock, open, or 6880 delegation state for any files and have not been used recently. 6881 The time period used to determine when to dispose of nfs_lockowners 6882 is an implementation choice. The time period should certainly be 6883 no less than the lease time plus any grace period the server wishes 6884 to implement beyond a lease time. The OPEN_CONFIRM operation 6885 allows the server to safely dispose of unused nfs_lockowner data 6886 structures. 6888 In the case that a client issues an OPEN operation and the server 6889 no longer has a record of the nfs_lockowner, the server needs 6890 ensure that this is a new OPEN and not a replay or retransmission. 6892 A lazy server implementation might require confirmation for every 6893 nfs_lockowner for which it has no record. However, this is not 6894 necessary until the server records the fact that it has disposed of 6895 one nfs_lockowner for the given clientid. 6897 The server must hold unconfirmed OPEN state until one of three 6898 events occur. First, the client sends an OPEN_CONFIRM request with 6899 the appropriate sequence id and confirmation verifier within the 6900 lease period. In this case, the OPEN state on the server goes to 6901 confirmed, and the nfs_lockowner on the server is fully 6902 established. 6904 Second, the client sends another OPEN request with a sequence id 6905 that is incorrect for the nfs_lockowner (out of sequence). In this 6906 case, the server assumes the second OPEN request is valid and the 6907 first one is a replay. The server cancels the OPEN state of the 6908 first OPEN requests, establishes an unconfirmed OPEN state for the 6909 second OPEN request, and responds to the second OPEN request with 6910 an indication that an OPEN_CONFIRM is needed. The process then 6911 repeats itself. While there is a potential for a denial of service 6912 attack on the client, it is mitigated if the client and server 6913 require the use of a security flavor based on Kerberos V5, LIPKEY, 6914 or some other flavor that uses cryptography. 6916 What if the server is in the unconfirmed OPEN state for a given 6917 nfs_lockowner, and it receives an operation on the nfs_lockowner 6918 that has a stateid but the operation is not OPEN, or it is 6919 OPEN_CONFIRM but with the wrong confirmation verifier? Then, even 6921 Draft Specification NFS version 4 Protocol February 2000 6923 if the seqid is correct, the server returns NFS4ERR_BAD_STATEID, 6924 because the server assumes the operation is a replay: if the server 6925 has no established OPEN state, then there is no way, for example, a 6926 LOCK operation could be valid. 6928 Third, neither of the two aforementioned events occur for the 6929 nfs_lockowner within the lease period. In this case, the OPEN 6930 state is cancelled and disposal of the nfs_lockowner can occur. 6932 ERRORS 6934 NFS4ERR_BADHANDLE 6935 NFS4ERR_BAD_SEQID 6936 NFS4ERR_EXPIRED 6937 NFS4ERR_FHEXPIRED 6938 NFS4ERR_GRACE 6939 NFS4ERR_INVAL 6940 NFS4ERR_MOVED 6941 NFS4ERR_NOENT 6942 NFS4ERR_NOFILEHANDLE 6943 NFS4ERR_NOTSUPP 6944 NFS4ERR_RESOURCE 6945 NFS4ERR_SERVERFAULT 6946 NFS4ERR_STALE 6947 NFS4ERR_WRONGSEC 6949 Draft Specification NFS version 4 Protocol February 2000 6951 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access 6953 SYNOPSIS 6955 (cfh), stateid, seqid, access, deny -> stateid 6957 ARGUMENT 6959 struct OPEN_DOWNGRADE4args { 6960 /* CURRENT_FH: opened file */ 6961 stateid4 stateid; 6962 seqid4 seqid; 6963 uint32_t share_access; 6964 uint32_t share_deny; 6965 }; 6967 RESULT 6969 struct OPEN_DOWNGRADE4resok { 6970 stateid4 stateid; 6971 }; 6973 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 6974 case NFS4_OK: 6975 OPEN_DOWNGRADE4resok resok4; 6976 default: 6977 void; 6978 }; 6980 This operation is used to adjust the access and deny bits for a given 6981 open. This is necessary when a given lockowner opens the same file 6982 multiple times with different access and deny flags. In this 6983 situation, a close of one of the open's may change the appropriate 6984 access and deny flags to remove bits associated with open's no longer 6985 in effect. 6987 The access and deny bits speicifed in this operation replace the 6988 current ones for the specified open file. If either the access or 6989 the deny mode specified includes bits not in effect for the open, the 6990 error NFS4ERR_INVAL should be returned. Since access and deny bits 6991 are subsets of those already granted, it is is not possible for this 6992 request to denied because of conflicting share reservations. 6994 On success, the current filehandle retains its value. 6996 Draft Specification NFS version 4 Protocol February 2000 6998 ERRORS 7000 NFS4ERR_BADHANDLE 7001 NFS4ERR_BAD_SEQID 7002 NFS4ERR_BAD_STATEID 7003 NFS4ERR_EXPIRED 7004 NFS4ERR_FHEXPIRED 7005 NFS4ERR_INVAL 7006 NFS4ERR_MOVED 7007 NFS4ERR_NOFILEHANDLE 7008 NFS4ERR_OLD_STATEID 7009 NFS4ERR_RESOURCE 7010 NFS4ERR_SERVERFAULT 7011 NFS4ERR_STALE 7012 NFS4ERR_STALE_STATEID 7014 Draft Specification NFS version 4 Protocol February 2000 7016 14.2.20. Operation 22: PUTFH - Set Current Filehandle 7018 SYNOPSIS 7020 filehandle -> (cfh) 7022 ARGUMENT 7024 struct PUTFH4args { 7025 nfs4_fh object; 7026 }; 7028 RESULT 7030 struct PUTFH4res { 7031 /* CURRENT_FH: */ 7032 nfsstat4 status; 7033 }; 7035 DESCRIPTION 7037 Replaces the current filehandle with the filehandle provided as an 7038 argument. 7040 IMPLEMENTATION 7042 Commonly used as the first operator in an NFS request to set the 7043 context for following operations. 7045 ERRORS 7047 NFS4ERR_BADHANDLE 7048 NFS4ERR_FHEXPIRED 7049 NFS4ERR_MOVED 7050 NFS4ERR_RESOURCE 7051 NFS4ERR_SERVERFAULT 7052 NFS4ERR_STALE 7053 NFS4ERR_WRONGSEC 7055 Draft Specification NFS version 4 Protocol February 2000 7057 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle 7059 SYNOPSIS 7061 - -> (cfh) 7063 ARGUMENT 7065 void; 7067 RESULT 7069 struct PUTPUBFH4res { 7070 /* CURRENT_FH: root fh */ 7071 nfsstat4 status; 7072 }; 7074 DESCRIPTION 7076 Replaces the current filehandle with the filehandle that represents 7077 the public filehandle of the server's name space. This filehandle 7078 may be different from the "root" filehandle which may be associated 7079 with some other directory on the server. 7081 IMPLEMENTATION 7083 Used as the first operator in an NFS request to set the context for 7084 following operations. 7086 ERRORS 7088 NFS4ERR_RESOURCE 7089 NFS4ERR_SERVERFAULT 7090 NFS4ERR_WRONGSEC 7092 Draft Specification NFS version 4 Protocol February 2000 7094 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle 7096 SYNOPSIS 7098 - -> (cfh) 7100 ARGUMENT 7102 void; 7104 RESULT 7106 struct PUTROOTFH4res { 7107 /* CURRENT_FH: root fh */ 7108 nfsstat4 status; 7109 }; 7111 DESCRIPTION 7113 Replaces the current filehandle with the filehandle that represents 7114 the root of the server's name space. From this filehandle a LOOKUP 7115 operation can locate any other filehandle on the server. This 7116 filehandle may be different from the "public" filehandle which may 7117 be associated with some other directory on the server. 7119 IMPLEMENTATION 7121 Commonly used as the first operator in an NFS request to set the 7122 context for following operations. 7124 ERRORS 7126 NFS4ERR_RESOURCE 7127 NFS4ERR_SERVERFAULT 7128 NFS4ERR_WRONGSEC 7130 Draft Specification NFS version 4 Protocol February 2000 7132 14.2.23. Operation 25: READ - Read from File 7134 SYNOPSIS 7136 (cfh), offset, count, stateid -> eof, data 7138 ARGUMENT 7140 struct READ4args { 7141 /* CURRENT_FH: file */ 7142 stateid4 stateid; 7143 offset4 offset; 7144 count4 count; 7145 }; 7147 RESULT 7149 struct READ4resok { 7150 bool eof; 7151 opaque data<>; 7152 }; 7154 union READ4res switch (nfsstat4 status) { 7155 case NFS4_OK: 7156 READ4resok resok4; 7157 default: 7158 void; 7159 }; 7161 DESCRIPTION 7163 The READ operation reads data from the regular file identified by 7164 the current filehandle. 7166 The client provides an offset of where the READ is to start and a 7167 count of how many bytes are to be read. An offset of 0 (zero) 7168 means to read data starting at the beginning of the file. If 7169 offset is greater than or equal to the size of the file, the 7170 status, NFS4_OK, is returned with a data length set to 0 (zero) and 7171 eof set to TRUE. The READ is subject to access permissions 7172 checking. 7174 If the client specifies a count value of 0 (zero), the READ 7175 succeeds and returns 0 (zero) bytes of data again subject to access 7176 permissions checking. The server may choose to return fewer bytes 7178 Draft Specification NFS version 4 Protocol February 2000 7180 than specified by the client. The client needs to check for this 7181 condition and handle the condition appropriately. 7183 The stateid value for a READ request represents a value returned 7184 from a previous record lock or share reservation request. Used by 7185 the server to verify that the associated lock is still valid and to 7186 update lease timeouts for the client. 7188 If the read ended at the end-of-file (formally, in a correctly 7189 formed READ request, if offset + count is equal to the size of the 7190 file), eof is returned as TRUE; otherwise it is FALSE. A successful 7191 READ of an empty file will always return eof as TRUE. 7193 IMPLEMENTATION 7195 It is possible for the server to return fewer than count bytes of 7196 data. If the server returns less than the count requested and eof 7197 set to FALSE, the client should issue another READ to get the 7198 remaining data. A server may return less data than requested under 7199 several circumstances. The file may have been truncated by another 7200 client or perhaps on the server itself, changing the file size from 7201 what the requesting client believes to be the case. This would 7202 reduce the actual amount of data available to the client. It is 7203 possible that the server may back off the transfer size and reduce 7204 the read request return. Server resource exhaustion may also occur 7205 necessitating a smaller read return. 7207 If the file is locked the server will return an NFS4ERR_LOCKED 7208 error. Since the lock may be of short duration, the client may 7209 choose to retransmit the READ request (with exponential backoff) 7210 until the operation succeeds. 7212 ERRORS 7214 NFS4ERR_ACCES 7215 NFS4ERR_BADHANDLE 7216 NFS4ERR_BAD_STATEID 7217 NFS4ERR_DELAY 7218 NFS4ERR_DENIED 7219 NFS4ERR_EXPIRED 7220 NFS4ERR_FHEXPIRED 7221 NFS4ERR_GRACE 7222 NFS4ERR_INVAL 7223 NFS4ERR_IO 7224 NFS4ERR_LOCKED 7225 NFS4ERR_LEASE_MOVED 7227 Draft Specification NFS version 4 Protocol February 2000 7229 NFS4ERR_MOVED 7230 NFS4ERR_NOFILEHANDLE 7231 NFS4ERR_NXIO 7232 NFS4ERR_OLD_STATEID 7233 NFS4ERR_RESOURCE 7234 NFS4ERR_SERVERFAULT 7235 NFS4ERR_STALE 7236 NFS4ERR_STALE_STATEID 7237 NFS4ERR_WRONGSEC 7239 Draft Specification NFS version 4 Protocol February 2000 7241 14.2.24. Operation 26: READDIR - Read Directory 7243 SYNOPSIS 7244 (cfh), cookie, cookieverf, dircount, maxcount, attrbits -> 7245 cookieverf { cookie, filename, attrbits, attributes } 7247 ARGUMENT 7249 struct READDIR4args { 7250 /* CURRENT_FH: directory */ 7251 nfs_cookie4 cookie; 7252 verifier4 cookieverf; 7253 count4 dircount; 7254 count4 maxcount; 7255 bitmap4 attr_request; 7256 }; 7258 RESULT 7260 struct entry4 { 7261 nfs_cookie4 cookie; 7262 component4 name; 7263 fattr4 attrs; 7264 entry4 *nextentry; 7265 }; 7267 struct dirlist4 { 7268 entry4 *entries; 7269 bool eof; 7270 }; 7272 struct READDIR4resok { 7273 verifier4 cookieverf; 7274 dirlist4 reply; 7275 }; 7277 union READDIR4res switch (nfsstat4 status) { 7278 case NFS4_OK: 7279 READDIR4resok resok4; 7280 default: 7281 void; 7282 }; 7284 DESCRIPTION 7286 Draft Specification NFS version 4 Protocol February 2000 7288 The READDIR operation retrieves a variable number of entries from a 7289 file system directory and returns client requested attributes for 7290 each entry along with information to allow the client to request 7291 additional directory entries in a subsequent READDIR. 7293 The arguments contain a cookie value that represents where the 7294 READDIR should start within the directory. A value of 0 (zero) for 7295 the cookie is used to start reading at the beginning of the 7296 directory. For subsequent READDIR requests, the client specifies a 7297 cookie value that is provided by the server on a previous READDIR 7298 request. 7300 The cookieverf value should be set to 0 (zero) when the cookie 7301 value is 0 (zero) (first directory read). On subsequent requests, 7302 it should be a cookieverf as returned by the server. The 7303 cookieverf must match that returned by the READDIR in which the 7304 cookie was acquired. 7306 The dircount portion of the argument is a hint of the maximum 7307 number of bytes of directory information that should be returned. 7308 This value is the XDR encoded length of the name of the directory 7309 entries and the cookie value for the entries. The server may 7310 return less data. 7312 The maxcount value of the argument is the maximum number of bytes 7313 for the result. This maximum size represents all of the data being 7314 returned and includes the XDR overhead. The server may return less 7315 data. If the server is unable to return a single directory entry 7316 within the maxcount limit, the error NFS4ERR_READDIR_NOSPC will be 7317 returned to the client. 7319 Finally, attrbits represents the list of attributes to be returned 7320 for each directory entry supplied by the server. 7322 On successful return, the server's response will provide a list of 7323 directory entries. Each of these entries contains the name of the 7324 directory entry, a cookie value for that entry, and the associated 7325 attributes as requested. 7327 The cookie value is only meaningful to the server and is used as a 7328 "bookmark" for the directory entry. As mentioned, this cookie is 7329 used by the client for subsequent READDIR operations so that it may 7330 continue reading a directory. The cookie is similar in concept to 7331 a READ offset but should not be interpreted as such by the client. 7332 Ideally, the cookie value should not change if the directory is 7333 modified. 7335 In some cases, the server may encounter an error while obtaining 7337 Draft Specification NFS version 4 Protocol February 2000 7339 the attributes for a directory entry. Instead of returning an 7340 error for the entire READDIR operation, the server can instead 7341 return the attribute 'fattr4_rdattr_error'. With this, the server 7342 is able to communicate the failure to the client and not fail the 7343 entire operation in the instance of what might be a transient 7344 failure. Obviously, the client must request the 7345 fattr4_rdattr_error attribute for this method to work properly. If 7346 the client does not request the attribute, the server has no choice 7347 but to return failure for the entire READDIR operation. 7349 For some file system environments, the directory entries "." and 7350 ".." have special meaning and in other environments, they may not. 7351 If the server supports these special entries within a directory, 7352 they should not be returned to the client as part of the READDIR 7353 response. To enable some client environments, the cookie values of 7354 0, 1, and 2 are to be considered reserved. For READDIR arguments, 7355 cookie values of 1 and 2 should not be used and for READDIR results 7356 cookie values of 0, 1, and 2 should not returned. 7358 IMPLEMENTATION 7360 The server's file system directory representations can differ 7361 greatly. A client's programming interfaces may also be bound to 7362 the local operating environment in a way that does not translate 7363 well into the NFS protocol. Therefore the use of the dircount and 7364 maxcount fields are provided to allow the client the ability to 7365 provide guidelines to the server. If the client is aggressive 7366 about attribute collection during a READDIR, the server has an idea 7367 of how to limit the encoded response. The dircount field provides 7368 a hint on the number of entries based solely on the names of the 7369 directory entries. Since it is a hint, it may be possible that a 7370 dircount value is zero. In this case, the server is free to ignore 7371 the dircount value and return directory information based on the 7372 specified maxcount value. 7374 The cookieverf may be used by the server to help manage cookie 7375 values that may become stale. It should be a rare occurrence that 7376 a server is unable to continue properly reading a directory with 7377 the provided cookie/cookieverf pair. The server should make every 7378 effort to avoid this condition since the application at the client 7379 may not be able to properly handle this type of failure. 7381 The use of the cookieverf will also protect the client from using 7382 READDIR cookie values that may be stale. For example, if the file 7383 system has been migrated, the server may or may not be able to use 7384 the same cookie values to service READDIR as the previous server 7385 used. With the client providing the cookieverf, the server is able 7387 Draft Specification NFS version 4 Protocol February 2000 7389 to provide the appropriate response to the client. This prevents 7390 the case where the server may accept a cookie value but the 7391 underlying directory has changed and the response is invalid from 7392 the client's context of its previous READDIR. 7394 Since the server will not be returning "." and ".." entries as has 7395 been done with previous versions of the NFS protocol, the client 7396 that requires these entries be present in READDIR responses must 7397 fabricate them. 7399 ERRORS 7401 NFS4ERR_ACCES 7402 NFS4ERR_BADHANDLE 7403 NFS4ERR_BAD_COOKIE 7404 NFS4ERR_DELAY 7405 NFS4ERR_FHEXPIRED 7406 NFS4ERR_INVAL 7407 NFS4ERR_IO 7408 NFS4ERR_MOVED 7409 NFS4ERR_NOFILEHANDLE 7410 NFS4ERR_NOTDIR 7411 NFS4ERR_NOTSUPP 7412 NFS4ERR_READDIR_NOSPC 7413 NFS4ERR_RESOURCE 7414 NFS4ERR_SERVERFAULT 7415 NFS4ERR_STALE 7416 NFS4ERR_TOOSMALL 7417 NFS4ERR_WRONGSEC 7419 Draft Specification NFS version 4 Protocol February 2000 7421 14.2.25. Operation 27: READLINK - Read Symbolic Link 7423 SYNOPSIS 7425 (cfh) -> linktext 7427 ARGUMENT 7429 /* CURRENT_FH: symlink */ 7430 void; 7432 RESULT 7434 struct READLINK4resok { 7435 linktext4 link; 7436 }; 7438 union READLINK4res switch (nfsstat4 status) { 7439 case NFS4_OK: 7440 READLINK4resok resok4; 7441 default: 7442 void; 7443 }; 7445 DESCRIPTION 7447 READLINK reads the data associated with a symbolic link. The data 7448 is a UTF-8 string that is opaque to the server. That is, whether 7449 created by an NFS client or created locally on the server, the data 7450 in a symbolic link is not interpreted when created, but is simply 7451 stored. 7453 IMPLEMENTATION 7455 A symbolic link is nominally a pointer to another file. The data 7456 is not necessarily interpreted by the server, just stored in the 7457 file. It is possible for a client implementation to store a path 7458 name that is not meaningful to the server operating system in a 7459 symbolic link. A READLINK operation returns the data to the client 7460 for interpretation. If different implementations want to share 7461 access to symbolic links, then they must agree on the 7462 interpretation of the data in the symbolic link. 7464 The READLINK operation is only allowed on objects of type, NF4LNK. 7466 Draft Specification NFS version 4 Protocol February 2000 7468 The server should return the error, NFS4ERR_INVAL, if the object is 7469 not of type, NF4LNK. 7471 ERRORS 7473 NFS4ERR_ACCES 7474 NFS4ERR_BADHANDLE 7475 NFS4ERR_DELAY 7476 NFS4ERR_FHEXPIRED 7477 NFS4ERR_INVAL 7478 NFS4ERR_IO 7479 NFS4ERR_MOVED 7480 NFS4ERR_NOFILEHANDLE 7481 NFS4ERR_NOTSUPP 7482 NFS4ERR_RESOURCE 7483 NFS4ERR_SERVERFAULT 7484 NFS4ERR_STALE 7485 NFS4ERR_WRONGSEC 7487 Draft Specification NFS version 4 Protocol February 2000 7489 14.2.26. Operation 28: REMOVE - Remove Filesystem Object 7491 SYNOPSIS 7493 (cfh), filename -> change_info 7495 ARGUMENT 7497 struct REMOVE4args { 7498 /* CURRENT_FH: directory */ 7499 component4 target; 7500 }; 7502 RESULT 7504 struct REMOVE4resok { 7505 change_info4 cinfo; 7506 } 7508 union REMOVE4res switch (nfsstat4 status) { 7509 case NFS4_OK: 7510 REMOVE4resok resok4; 7511 default: 7512 void; 7513 } 7515 DESCRIPTION 7517 The REMOVE operation removes (deletes) a directory entry named by 7518 filename from the directory corresponding to the current 7519 filehandle. If the entry in the directory was the last reference 7520 to the corresponding file system object, the object may be 7521 destroyed. 7523 For the directory where the filename was removed, the server 7524 returns change_info4 information in cinfo. With the atomic field 7525 of the change_info4 struct, the server will indicate if the before 7526 and after change attributes were obtained atomically with respect 7527 to the removal. 7529 If the target has a length of 0 (zero), or if target does not obey 7530 the UTF-8 definition, the error NFS4ERR_INVAL will be returned. 7532 IMPLEMENTATION 7534 Draft Specification NFS version 4 Protocol February 2000 7536 NFS versions 2 and 3 required a different operator RMDIR for 7537 directory removal. NFS version 4 REMOVE can be used to delete any 7538 directory entry independent of its file type. 7540 The concept of last reference is server specific. However, if the 7541 numlinks field in the previous attributes of the object had the 7542 value 1, the client should not rely on referring to the object via 7543 a file handle. Likewise, the client should not rely on the 7544 resources (disk space, directory entry, and so on.) formerly 7545 associated with the object becoming immediately available. Thus, if 7546 a client needs to be able to continue to access a file after using 7547 REMOVE to remove it, the client should take steps to make sure that 7548 the file will still be accessible. The usual mechanism used is to 7549 use RENAME to rename the file from its old name to a new hidden 7550 name. 7552 ERRORS 7554 NFS4ERR_ACCES 7555 NFS4ERR_BADHANDLE 7556 NFS4ERR_DELAY 7557 NFS4ERR_FHEXPIRED 7558 NFS4ERR_IO 7559 NFS4ERR_MOVED 7560 NFS4ERR_NAMETOOLONG 7561 NFS4ERR_NOENT 7562 NFS4ERR_NOFILEHANDLE 7563 NFS4ERR_NOTDIR 7564 NFS4ERR_NOTEMPTY 7565 NFS4ERR_NOTSUPP 7566 NFS4ERR_RESOURCE 7567 NFS4ERR_ROFS 7568 NFS4ERR_SERVERFAULT 7569 NFS4ERR_STALE 7570 NFS4ERR_WRONGSEC 7572 Draft Specification NFS version 4 Protocol February 2000 7574 14.2.27. Operation 29: RENAME - Rename Directory Entry 7576 SYNOPSIS 7578 (sfh), oldname (cfh), newname -> source_change_info, 7579 target_change_info 7581 ARGUMENT 7583 struct RENAME4args { 7584 /* SAVED_FH: source directory */ 7585 component4 oldname; 7586 /* CURRENT_FH: target directory */ 7587 component4 newname; 7588 }; 7590 RESULT 7592 struct RENAME4resok { 7593 change_info4 source_cinfo; 7594 change_info4 target_cinfo; 7595 }; 7597 union RENAME4res switch (nfsstat4 status) { 7598 case NFS4_OK: 7599 RENAME4resok resok4; 7600 default: 7601 void; 7602 }; 7604 DESCRIPTION 7606 The RENAME operation renames the object identified by oldname in 7607 the source directory corresponding to the saved filehandle, as set 7608 by the SAVEFH operation, to newname in the target directory 7609 corresponding to the current filehandle. The operation is required 7610 to be atomic to the client. Source and target directories must 7611 reside on the same file system on the server. On success, the 7612 current filehandle will continue to be the target directory. 7614 If the target directory already contains an entry with the name, 7615 newname, the source object must be compatible with the target: 7616 either both are non-directories or both are directories and the 7617 target must be empty. If compatible, the existing target is 7618 removed before the rename occurs. If they are not compatible or if 7620 Draft Specification NFS version 4 Protocol February 2000 7622 the target is a directory but not empty, the server will return the 7623 error, NFS4ERR_EXIST. 7625 If oldname and newname both refer to the same file (they might be 7626 hard links of each other), then RENAME should perform no action and 7627 return success. 7629 For both directories involved in the RENAME, the server returns 7630 change_info4 information. With the atomic field of the 7631 change_info4 struct, the server will indicate if the before and 7632 after change attributes were obtained atomically with respect to 7633 the rename. 7635 If the oldname or newname has a length of 0 (zero), or if oldname 7636 or newname does not obey the UTF-8 definition, the error 7637 NFS4ERR_INVAL will be returned. 7639 IMPLEMENTATION 7641 The RENAME operation must be atomic to the client. The statement 7642 "source and target directories must reside on the same file system 7643 on the server" means that the fsid fields in the attributes for the 7644 directories are the same. If they reside on different file systems, 7645 the error, NFS4ERR_XDEV, is returned. 7647 A filehandle may or may not become stale or expire on a rename. 7648 However, server implementors are strongly encouraged to attempt to 7649 keep file handles from becoming stale or expiring in this fashion. 7651 On some servers, the filenames, "." and "..", are illegal as either 7652 oldname or newname. In addition, neither oldname nor newname can 7653 be an alias for the source directory. These servers will return 7654 the error, NFS4ERR_INVAL, in these cases. 7656 ERRORS 7658 NFS4ERR_ACCES 7659 NFS4ERR_BADHANDLE 7660 NFS4ERR_DELAY 7661 NFS4ERR_DQUOT 7662 NFS4ERR_EXIST 7663 NFS4ERR_FHEXPIRED 7664 NFS4ERR_INVAL 7665 NFS4ERR_IO 7666 NFS4ERR_ISDIR 7668 Draft Specification NFS version 4 Protocol February 2000 7670 NFS4ERR_MOVED 7671 NFS4ERR_NAMETOOLONG 7672 NFS4ERR_NOENT 7673 NFS4ERR_NOFILEHANDLE 7674 NFS4ERR_NOSPC 7675 NFS4ERR_NOTDIR 7676 NFS4ERR_NOTEMPTY 7677 NFS4ERR_NOTSUPP 7678 NFS4ERR_RESOURCE 7679 NFS4ERR_ROFS 7680 NFS4ERR_SERVERFAULT 7681 NFS4ERR_STALE 7682 NFS4ERR_WRONGSEC 7683 NFS4ERR_XDEV 7685 Draft Specification NFS version 4 Protocol February 2000 7687 14.2.28. Operation 30: RENEW - Renew a Lease 7689 SYNOPSIS 7691 stateid -> () 7693 ARGUMENT 7695 struct RENEW4args { 7696 stateid4 stateid; 7697 }; 7699 RESULT 7701 struct RENEW4res { 7702 nfsstat4 status; 7703 }; 7705 DESCRIPTION 7707 The RENEW operation is used by the client to renew leases which it 7708 currently holds at a server. In processing the RENEW request, the 7709 server renews all leases associated with the client. The 7710 associated leases are determined by the client id provided via the 7711 SETCLIENTID procedure. 7713 The stateid for RENEW may not be one of the special stateids 7714 consisting of all bits 0 (zero) or all bits 1. 7716 IMPLEMENTATION 7718 ERRORS 7720 NFS4ERR_BAD_STATEID 7721 NFS4ERR_EXPIRED 7722 NFS4ERR_GRACE 7723 NFS4ERR_INVAL 7724 NFS4ERR_LEASE_MOVED 7725 NFS4ERR_MOVED 7726 NFS4ERR_OLD_STATEID 7727 NFS4ERR_RESOURCE 7728 NFS4ERR_SERVERFAULT 7730 Draft Specification NFS version 4 Protocol February 2000 7732 NFS4ERR_STALE_STATEID 7733 NFS4ERR_WRONGSEC 7735 Draft Specification NFS version 4 Protocol February 2000 7737 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle 7739 SYNOPSIS 7741 (sfh) -> (cfh) 7743 ARGUMENT 7745 /* SAVED_FH: */ 7746 void; 7748 RESULT 7750 struct RESTOREFH4res { 7751 /* CURRENT_FH: value of saved fh */ 7752 nfsstat4 status; 7753 }; 7755 DESCRIPTION 7757 Set the current filehandle to the value in the saved filehandle. 7758 If there is no saved filehandle then return an error 7759 NFS4ERR_NOFILEHANDLE. 7761 IMPLEMENTATION 7763 Operations like OPEN and LOOKUP use the current filehandle to 7764 represent a directory and replace it with a new filehandle. 7765 Assuming the previous filehandle was saved with a SAVEFH operator, 7766 the previous filehandle can be restored as the current filehandle. 7767 This is commonly used to obtain post-operation attributes for the 7768 directory, e.g. 7770 PUTFH (directory filehandle) 7771 SAVEFH 7772 GETATTR attrbits (pre-op dir attrs) 7773 CREATE optbits "foo" attrs 7774 GETATTR attrbits (file attributes) 7775 RESTOREFH 7776 GETATTR attrbits (post-op dir attrs) 7778 ERRORS 7780 Draft Specification NFS version 4 Protocol February 2000 7782 NFS4ERR_BADHANDLE 7783 NFS4ERR_FHEXPIRED 7784 NFS4ERR_MOVED 7785 NFS4ERR_NOFILEHANDLE 7786 NFS4ERR_RESOURCE 7787 NFS4ERR_SERVERFAULT 7788 NFS4ERR_STALE 7789 NFS4ERR_WRONGSEC 7791 Draft Specification NFS version 4 Protocol February 2000 7793 14.2.30. Operation 32: SAVEFH - Save Current Filehandle 7795 SYNOPSIS 7797 (cfh) -> (sfh) 7799 ARGUMENT 7801 /* CURRENT_FH: */ 7802 void; 7804 RESULT 7806 struct SAVEFH4res { 7807 /* SAVED_FH: value of current fh */ 7808 nfsstat4 status; 7809 }; 7811 DESCRIPTION 7813 Save the current filehandle. If a previous filehandle was saved 7814 then it is no longer accessible. The saved filehandle can be 7815 restored as the current filehandle with the RESTOREFH operator. 7817 On success, the current filehandle retains its value. 7819 IMPLEMENTATION 7821 ERRORS 7823 NFS4ERR_BADHANDLE 7824 NFS4ERR_FHEXPIRED 7825 NFS4ERR_MOVED 7826 NFS4ERR_NOFILEHANDLE 7827 NFS4ERR_RESOURCE 7828 NFS4ERR_SERVERFAULT 7829 NFS4ERR_STALE 7830 NFS4ERR_WRONGSEC 7832 Draft Specification NFS version 4 Protocol February 2000 7834 14.2.31. Operation 33: SECINFO - Obtain Available Security 7836 SYNOPSIS 7838 (cfh), name -> { secinfo } 7840 ARGUMENT 7842 struct SECINFO4args { 7843 /* CURRENT_FH: */ 7844 component4 name; 7845 }; 7847 RESULT 7849 enum rpc_gss_svc_t { 7850 RPC_GSS_SVC_NONE = 1, 7851 RPC_GSS_SVC_INTEGRITY = 2, 7852 RPC_GSS_SVC_PRIVACY = 3 7853 }; 7855 struct rpcsec_gss_info { 7856 sec_oid4 oid; 7857 qop4 qop; 7858 rpc_gss_svc_t service; 7859 }; 7861 struct secinfo4 { 7862 uint32_t flavor; 7863 opaque flavor_info<>; /* null for AUTH_SYS, AUTH_NONE; 7864 contains rpcsec_gss_info for 7865 RPCSEC_GSS. */ 7866 }; 7868 typedef secinfo4 SECINFO4resok<>; 7870 union SECINFO4res switch (nfsstat4 status) { 7871 case NFS4_OK: 7872 SECINFO4resok resok4; 7873 default: 7874 void; 7875 }; 7877 DESCRIPTION 7879 Draft Specification NFS version 4 Protocol February 2000 7881 The SECINFO operation is used by the client to obtain a list of 7882 valid RPC authentication flavors for a specific file handle, file 7883 name pair. The result will contain an array which represents the 7884 security mechanisms available. The array entries are represented 7885 by the secinfo4 structure. The field 'flavor' will contain a value 7886 of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or RPCSEC_GSS (as 7887 defined in [RFC2203]). 7889 For the flavors, AUTH_NONE, and AUTH_SYS no additional security 7890 information is returned. For a return value of RPCSEC_GSS, a 7891 security triple is returned that contains the mechanism object id 7892 (as defined in [RFC2078]), the quality of protection (as defined in 7893 [RFC2078]) and the service type (as defined in [RFC2203]). It is 7894 possible for SECINFO to return multiple entries with flavor equal 7895 to RPCSEC_GSS with different security triple values. 7897 IMPLEMENTATION 7899 The SECINFO operation is expected to be used by the NFS client when 7900 the error value of NFS4ERR_WRONGSEC is returned from another NFS 7901 operation. This signifies to the client that the server's security 7902 policy is different from what the client is currently using. At 7903 this point, the client is expected to obtain a list of possible 7904 security flavors and choose what best suits its policies. 7906 It is recommended that the client issue the SECINFO call protected 7907 by a security triple that uses either rpc_gss_svc_integrity or 7908 rpc_gss_svc_privacy service. The use of rpc_gss_svc_none would 7909 allow an attacker in the middle to modify the SECINFO results such 7910 that the client might select a weaker algorithm in the set allowed 7911 by server, making the client and/or server vulnerable to further 7912 attacks. 7914 ERRORS 7916 NFS4ERR_BADHANDLE 7917 NFS4ERR_FHEXPIRED 7918 NFS4ERR_MOVED 7919 NFS4ERR_NAMETOOLONG 7920 NFS4ERR_NOENT 7921 NFS4ERR_NOFILEHANDLE 7922 NFS4ERR_NOTDIR 7923 NFS4ERR_RESOURCE 7924 NFS4ERR_SERVERFAULT 7925 NFS4ERR_STALE 7926 NFS4ERR_WRONGSEC 7928 Draft Specification NFS version 4 Protocol February 2000 7930 14.2.32. Operation 34: SETATTR - Set Attributes 7932 SYNOPSIS 7934 (cfh), attrbits, attrvals -> - 7936 ARGUMENT 7938 struct SETATTR4args { 7939 /* CURRENT_FH: target object */ 7940 stateid4 stateid; 7941 fattr4 obj_attributes; 7942 }; 7944 RESULT 7946 struct SETATTR4res { 7947 nfsstat4 status; 7948 bitmap4 attrsset; 7949 }; 7951 DESCRIPTION 7953 The SETATTR operation changes one or more of the attributes of a 7954 file system object. The new attributes are specified with a bitmap 7955 and the attributes that follow the bitmap in bit order. 7957 The stateid is necessary for SETATTRs that change the size of file 7958 (modify the attribute object_size). This stateid represents a 7959 record lock, share reservation, or delegation which must be valid 7960 for the SETATTR to modify the file data. A valid stateid would 7961 always be specified. When the file size is not changed, the 7962 special stateid consisting of all bits 0 (zero) should be used. 7964 On either success or failure of the operation, the server will 7965 return the attrsset bitmask to represent what (if any) attributes 7966 were successfully set. 7968 IMPLEMENTATION 7970 The file size attribute is used to request changes to the size of a 7971 file. A value of 0 (zero) causes the file to be truncated, a value 7972 less than the current size of the file causes data from new size to 7973 the end of the file to be discarded, and a size greater than the 7975 Draft Specification NFS version 4 Protocol February 2000 7977 current size of the file causes logically zeroed data bytes to be 7978 added to the end of the file. Servers are free to implement this 7979 using holes or actual zero data bytes. Clients should not make any 7980 assumptions regarding a server's implementation of this feature, 7981 beyond that the bytes returned will be zeroed. Servers must 7982 support extending the file size via SETATTR. 7984 SETATTR is not guaranteed atomic. A failed SETATTR may partially 7985 change a file's attributes. 7987 Changing the size of a file with SETATTR indirectly changes the 7988 time_modify. A client must account for this as size changes can 7989 result in data deletion. 7991 If server and client times differ, programs that compare client 7992 time to file times can break. A time maintenance protocol should be 7993 used to limit client/server time skew. 7995 If the server cannot successfully set all the attributes it must 7996 return an NFS4ERR_INVAL error. If the server can only support 32 7997 bit offsets and sizes, a SETATTR request to set the size of a file 7998 to larger than can be represented in 32 bits will be rejected with 7999 this same error. 8001 ERRORS 8003 NFS4ERR_ACCES 8004 NFS4ERR_BADHANDLE 8005 NFS4ERR_BAD_STATEID 8006 NFS4ERR_DELAY 8007 NFS4ERR_DENIED 8008 NFS4ERR_DQUOT 8009 NFS4ERR_EXPIRED 8010 NFS4ERR_FBIG 8011 NFS4ERR_FHEXPIRED 8012 NFS4ERR_GRACE 8013 NFS4ERR_INVAL 8014 NFS4ERR_IO 8015 NFS4ERR_MOVED 8016 NFS4ERR_NOFILEHANDLE 8017 NFS4ERR_NOSPC 8018 NFS4ERR_NOTSUPP 8019 NFS4ERR_OLD_STATEID 8020 NFS4ERR_PERM 8021 NFS4ERR_RESOURCE 8022 NFS4ERR_ROFS 8023 NFS4ERR_SERVERFAULT 8025 Draft Specification NFS version 4 Protocol February 2000 8027 NFS4ERR_STALE 8028 NFS4ERR_STALE_STATEID 8029 NFS4ERR_WRONGSEC 8031 Draft Specification NFS version 4 Protocol February 2000 8033 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid 8035 SYNOPSIS 8037 client, callback -> clientid, setclientid_confirm 8039 ARGUMENT 8041 struct SETCLIENTID4args { 8042 nfs_client_id4 client; 8043 cb_client4 callback; 8044 }; 8046 RESULT 8048 struct SETCLIENTID4resok { 8049 clientid4 clientid; 8050 verifier4 setclientid_confirm; 8051 }; 8053 union SETCLIENTID4res switch (nfsstat4 status) { 8054 case NFS4_OK: 8055 SETCLIENTID4resok resok4; 8056 case NFS4ERR_CLID_INUSE: 8057 clientaddr4 client_using; 8058 default: 8059 void; 8060 }; 8062 DESCRIPTION 8064 The SETCLIENTID operation introduces the ability of the client to 8065 notify the server of its intention to use a particular client 8066 identifier and verifier pair. Upon successful completion the 8067 server will return a clientid which is used in subsequent file 8068 locking requests and a confirmation verifier. The client will use 8069 the SETCLIENTID_CONFIRM operation to return the verifier to the 8070 server. At that point, the client may use the clientid in 8071 subsequent operations that require an nfs_lockowner. 8073 The callback information provided in this operation will be used if 8074 the client is provided an open delegation at a future point. 8075 Therefore, the client must correctly reflect the program and port 8076 numbers for the callback program at the time SETCLIENTID is used. 8078 Draft Specification NFS version 4 Protocol February 2000 8080 IMPLEMENTATION 8082 The server takes the verifier and client identification supplied in 8083 the nfs_client_id4 and searches for a match of the client 8084 identification. If no match is found the server saves the 8085 principal/uid information along with the verifier and client 8086 identification and returns a unique clientid that is used as a 8087 shorthand reference to the supplied information. 8089 If the server finds matching client identification and a 8090 corresponding match in principal/uid, the server releases all 8091 locking state for the client and returns a new clientid. 8093 The principal or principal to user identifier mapping is taken from 8094 the credential presented in the RPC. As mentioned, the server will 8095 use the credential and associated principal for the matching with 8096 existing clientids. If the client is a traditional host based 8097 client like a Unix NFS client, then the credential presented may be 8098 the host credential. If the client is a user level client or light 8099 weight client, the credential used may be the end user's 8100 credential. The client should take care in choosing an appropriate 8101 credential since denial of service attacks could be attempted by a 8102 rogue client that has access to the credential. 8104 ERRORS 8106 NFS4ERR_CLID_INUSE 8107 NFS4ERR_INVAL 8108 NFS4ERR_RESOURCE 8109 NFS4ERR_SERVERFAULT 8111 Draft Specification NFS version 4 Protocol February 2000 8113 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 8115 SYNOPSIS 8117 setclientid_confirm -> - 8119 ARGUMENT 8121 struct SETCLIENTID_CONFIRM4args { 8122 verifier4 setclientid_confirm; 8123 }; 8125 RESULT 8127 struct SETCLIENTID_CONFIRM4res { 8128 nfsstat4 status; 8129 }; 8131 DESCRIPTION 8133 This operation is used by the client to confirm the results from a 8134 previous call to SETCLIENTID. The client provides the server 8135 supplied (from a SETCLIENTID response) opaque confirmation 8136 verifier. The server responds with a simple status of success or 8137 failure. 8139 IMPLEMENTATION 8141 The client must use the SETCLIENTID_CONFIRM operation to confirm 8142 its use of client identifier. Once the server receives the valid 8143 confirmation, all state previously held by the client (if 8144 applicable) is kept until the receipt of the SETCLIENTID_CONFIRM is 8145 successful. Upon successful confirmation the server will release 8146 the previous state held on behalf of the client. The server should 8147 choose a confirmation cookie value that is reasonably unique for 8148 the client. 8150 ERRORS 8152 NFS4ERR_CLID_INUSE 8153 NFS4ERR_INVAL 8154 NFS4ERR_RESOURCE 8155 NFS4ERR_SERVERFAULT 8157 Draft Specification NFS version 4 Protocol February 2000 8159 NFS4ERR_STALE_CLIENTID 8161 Draft Specification NFS version 4 Protocol February 2000 8163 14.2.35. Operation 37: VERIFY - Verify Same Attributes 8165 SYNOPSIS 8167 (cfh), attrbits, attrvals -> - 8169 ARGUMENT 8171 struct VERIFY4args { 8172 /* CURRENT_FH: object */ 8173 bitmap4 attr_request; 8174 fattr4 obj_attributes; 8175 }; 8177 RESULT 8179 struct VERIFY4res { 8180 nfsstat4 status; 8181 }; 8183 DESCRIPTION 8185 The VERIFY operation is used to verify that attributes have a value 8186 assumed by the client before proceeding with following operations 8187 in the compound request. If any of the attributes do not match 8188 then the error NFS4ERR_NOT_SAME must be returned. The current 8189 filehandle retains its value after successful completion of the 8190 operation. 8192 IMPLEMENTATION 8194 One possible use of the VERIFY operation is the following compound 8195 sequence. With this the client is attempting to verify that the 8196 file being removed will match what the client expects to be 8197 removed. This sequence can help prevent the unintended deletion of 8198 a file. 8200 PUTFH (directory filehandle) 8201 LOOKUP (file name) 8202 VERIFY (filehandle == fh) 8203 PUTFH (directory filehandle) 8204 REMOVE (file name) 8206 This sequence does not prevent a second client from removing and 8207 creating a new file in the middle of this sequence but it does help 8209 Draft Specification NFS version 4 Protocol February 2000 8211 avoid the unintended result. 8213 In the case that a recommended attribute is specified in the VERIFY 8214 operation and the server does not support that attribute for the 8215 file system object, the error NFS4ERR_NOTSUPP is returned to the 8216 client. 8218 ERRORS 8220 NFS4ERR_ACCES 8221 NFS4ERR_BADHANDLE 8222 NFS4ERR_DELAY 8223 NFS4ERR_FHEXPIRED 8224 NFS4ERR_INVAL 8225 NFS4ERR_MOVED 8226 NFS4ERR_NOFILEHANDLE 8227 NFS4ERR_NOTSUPP 8228 NFS4ERR_NOT_SAME 8229 NFS4ERR_RESOURCE 8230 NFS4ERR_SERVERFAULT 8231 NFS4ERR_STALE 8232 NFS4ERR_WRONGSEC 8234 Draft Specification NFS version 4 Protocol February 2000 8236 14.2.36. Operation 38: WRITE - Write to File 8238 SYNOPSIS 8240 (cfh), offset, count, stability, stateid, data -> count, committed, 8241 verifier 8243 ARGUMENT 8245 enum stable_how4 { 8246 UNSTABLE4 = 0, 8247 DATA_SYNC4 = 1, 8248 FILE_SYNC4 = 2 8249 }; 8251 struct WRITE4args { 8252 /* CURRENT_FH: file */ 8253 stateid4 stateid; 8254 offset4 offset; 8255 stable_how4 stable; 8256 opaque data<>; 8257 }; 8259 RESULT 8261 struct WRITE4resok { 8262 count4 count; 8263 stable_how4 committed; 8264 verifier4writeverf; 8265 }; 8267 union WRITE4res switch (nfsstat4 status) { 8268 case NFS4_OK: 8269 WRITE4resok resok4; 8270 default: 8271 void; 8272 }; 8274 DESCRIPTION 8276 The WRITE operation is used to write data to a regular file. The 8277 target file is specified by the current filehandle. The offset 8278 specifies the offset where the data should be written. An offset 8279 of 0 (zero) specifies that the write should start at the beginning 8280 of the file. The count represents the number of bytes of data that 8282 Draft Specification NFS version 4 Protocol February 2000 8284 are to be written. If the count is 0 (zero), the WRITE will 8285 succeed and return a count of 0 (zero) subject to permissions 8286 checking. The server may choose to write fewer bytes than 8287 requested by the client. 8289 Part of the write request is a specification of how the write is to 8290 be performed. The client specifies with the stable parameter the 8291 method of how the data is to be processed by the server. If stable 8292 is FILE_SYNC4, the server must commit the data written plus all 8293 file system metadata to stable storage before returning results. 8294 This corresponds to the NFS version 2 protocol semantics. Any 8295 other behavior constitutes a protocol violation. If stable is 8296 DATA_SYNC4, then the server must commit all of the data to stable 8297 storage and enough of the metadata to retrieve the data before 8298 returning. The server implementor is free to implement DATA_SYNC4 8299 in the same fashion as FILE_SYNC4, but with a possible performance 8300 drop. If stable is UNSTABLE4, the server is free to commit any 8301 part of the data and the metadata to stable storage, including all 8302 or none, before returning a reply to the client. There is no 8303 guarantee whether or when any uncommitted data will subsequently be 8304 committed to stable storage. The only guarantees made by the server 8305 are that it will not destroy any data without changing the value of 8306 verf and that it will not commit the data and metadata at a level 8307 less than that requested by the client. 8309 The stateid returned from a previous record lock or share 8310 reservation request is provided as part of the argument. The 8311 stateid is used by the server to verify that the associated lock is 8312 still valid and to update lease timeouts for the client. 8314 Upon successful completion, the following results are returned. 8315 The count result is the number of bytes of data written to the 8316 file. The server may write fewer bytes than requested. If so, the 8317 actual number of bytes written starting at location, offset, is 8318 returned. 8320 The server also returns an indication of the level of commitment of 8321 the data and metadata via committed. If the server committed all 8322 data and metadata to stable storage, committed should be set to 8323 FILE_SYNC4. If the level of commitment was at least as strong as 8324 DATA_SYNC4, then committed should be set to DATA_SYNC4. Otherwise, 8325 committed must be returned as UNSTABLE4. If stable was FILE4_SYNC, 8326 then committed must also be FILE_SYNC4: anything else constitutes a 8327 protocol violation. If stable was DATA_SYNC4, then committed may be 8328 FILE_SYNC4 or DATA_SYNC4: anything else constitutes a protocol 8329 violation. If stable was UNSTABLE4, then committed may be either 8330 FILE_SYNC4, DATA_SYNC4, or UNSTABLE4. 8332 Draft Specification NFS version 4 Protocol February 2000 8334 The final portion of the result is the write verifier, verf. The 8335 write verifier is a cookie that the client can use to determine 8336 whether the server has changed state between a call to WRITE and a 8337 subsequent call to either WRITE or COMMIT. This cookie must be 8338 consistent during a single instance of the NFS version 4 protocol 8339 service and must be unique between instances of the NFS version 4 8340 protocol server, where uncommitted data may be lost. 8342 If a client writes data to the server with the stable argument set 8343 to UNSTABLE4 and the reply yields a committed response of 8344 DATA_SYNC4 or UNSTABLE4, the client will follow up some time in the 8345 future with a COMMIT operation to synchronize outstanding 8346 asynchronous data and metadata with the server's stable storage, 8347 barring client error. It is possible that due to client crash or 8348 other error that a subsequent COMMIT will not be received by the 8349 server. 8351 On success, the current filehandle retains its value. 8353 IMPLEMENTATION 8355 It is possible for the server to write fewer than count bytes of 8356 data. In this case, the server should not return an error unless 8357 no data was written at all. If the server writes less than count 8358 bytes, the client should issue another WRITE to write the remaining 8359 data. 8361 It is assumed that the act of writing data to a file will cause the 8362 time_modified of the file to be updated. However, the 8363 time_modified of the file should not be changed unless the contents 8364 of the file are changed. Thus, a WRITE request with count set to 0 8365 should not cause the time_modified of the file to be updated. 8367 The definition of stable storage has been historically a point of 8368 contention. The following expected properties of stable storage 8369 may help in resolving design issues in the implementation. Stable 8370 storage is persistent storage that survives: 8372 1. Repeated power failures. 8373 2. Hardware failures (of any board, power supply, etc.). 8374 3. Repeated software crashes, including reboot cycle. 8376 This definition does not address failure of the stable storage 8377 module itself. 8379 Draft Specification NFS version 4 Protocol February 2000 8381 The verifier is defined to allow a client to detect different 8382 instances of an NFS version 4 protocol server over which cached, 8383 uncommitted data may be lost. In the most likely case, the verifier 8384 allows the client to detect server reboots. This information is 8385 required so that the client can safely determine whether the server 8386 could have lost cached data. If the server fails unexpectedly and 8387 the client has uncommitted data from previous WRITE requests (done 8388 with the stable argument set to UNSTABLE4 and in which the result 8389 committed was returned as UNSTABLE4 as well) it may not have 8390 flushed cached data to stable storage. The burden of recovery is on 8391 the client and the client will need to retransmit the data to the 8392 server. 8394 A suggested verifier would be to use the time that the server was 8395 booted or the time the server was last started (if restarting the 8396 server without a reboot results in lost buffers). 8398 The committed field in the results allows the client to do more 8399 effective caching. If the server is committing all WRITE requests 8400 to stable storage, then it should return with committed set to 8401 FILE_SYNC4, regardless of the value of the stable field in the 8402 arguments. A server that uses an NVRAM accelerator may choose to 8403 implement this policy. The client can use this to increase the 8404 effectiveness of the cache by discarding cached data that has 8405 already been committed on the server. 8407 Some implementations may return NFS4ERR_NOSPC instead of 8408 NFS4ERR_DQUOT when a user's quota is exceeded. 8410 ERRORS 8412 NFS4ERR_ACCES 8413 NFS4ERR_BADHANDLE 8414 NFS4ERR_BAD_STATEID 8415 NFS4ERR_DELAY 8416 NFS4ERR_DENIED 8417 NFS4ERR_DQUOT 8418 NFS4ERR_EXPIRED 8419 NFS4ERR_FBIG 8420 NFS4ERR_FHEXPIRED 8421 NFS4ERR_GRACE 8422 NFS4ERR_INVAL 8423 NFS4ERR_IO 8424 NFS4ERR_LEASE_MOVED 8425 NFS4ERR_LOCKED 8426 NFS4ERR_MOVED 8427 NFS4ERR_NOFILEHANDLE 8429 Draft Specification NFS version 4 Protocol February 2000 8431 NFS4ERR_NOSPC 8432 NFS4ERR_OLD_STATEID 8433 NFS4ERR_RESOURCE 8434 NFS4ERR_ROFS 8435 NFS4ERR_SERVERFAULT 8436 NFS4ERR_STALE 8437 NFS4ERR_STALE_STATEID 8438 NFS4ERR_WRONGSEC 8440 Draft Specification NFS version 4 Protocol February 2000 8442 15. NFS Version 4 Callback Procedures 8444 The procedures used for callbacks are defined in the following 8445 sections. In the interest of clarity, the terms "client" and 8446 "server" refer to NFS clients and servers, despite the fact that for 8447 an individual callback RPC, the sense of these terms would be 8448 precisely the opposite. 8450 15.1. Procedure 0: CB_NULL - No Operation 8452 SYNOPSIS 8454 8456 ARGUMENT 8458 void; 8460 RESULT 8462 void; 8464 DESCRIPTION 8466 Standard NULL procedure. Void argument, void response. This 8467 procedure has no functionality associated with it. 8469 ERRORS 8471 None. 8473 Draft Specification NFS version 4 Protocol February 2000 8475 15.2. Procedure 1: CB_COMPOUND - Compound Operations 8477 SYNOPSIS 8479 compoundargs -> compoundres 8481 ARGUMENT 8483 enum nfs_cb_opnum4 { 8484 OP_CB_GETATTR = 3, 8485 OP_CB_RECALL = 4 8486 }; 8488 union nfs_cb_argop4 switch (unsigned argop) { 8489 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 8490 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 8491 }; 8493 struct CB_COMPOUND4args { 8494 utf8string tag; 8495 uint32_t minorversion; 8496 nfs_cb_argop4 argarray<>; 8497 }; 8499 RESULT 8501 union nfs_cb_resop4 switch (unsigned resop){ 8502 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 8503 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 8504 }; 8506 struct CB_COMPOUND4args { 8507 utf8string tag; 8508 uint32_t minorversion; 8509 nfs_cb_argop4 argarray<>; 8510 }; 8512 struct CB_COMPOUND4res { 8513 nfsstat4 status; 8514 utf8string tag; 8515 nfs_cb_resop4 resarray<>; 8516 }; 8518 DESCRIPTION 8520 Draft Specification NFS version 4 Protocol February 2000 8522 The CB_COMPOUND procedure is used to combine one or more of the 8523 callback procedures into a single RPC request. The main callback 8524 RPC program has two main procedures: CB_NULL and CB_COMPOUND. All 8525 other operations use the CB_COMPOUND procedure as a wrapper. 8527 In the processing of the CB_COMPOUND procedure, the client may find 8528 that it does not have the available resources to execute any or all 8529 of the operations within the CB_COMPOUND sequence. In this case, 8530 the error NFS4ERR_RESOURCE will be returned for the particular 8531 operation within the CB_COMPOUND procedure where the resource 8532 exhaustion occurred. This assumes that all previous operations 8533 within the CB_COMPOUND sequence have been evaluated successfully. 8535 Contained within the CB_COMPOUND results is a 'status' field. This 8536 status must be equivalent to the status of the last operation that 8537 was executed within the CB_COMPOUND procedure. Therefore, if an 8538 operation incurred an error then the 'status' value will be the 8539 same error value as is being returned for the operation that 8540 failed. 8542 IMPLEMENTATION 8544 The CB_COMPOUND procedure is used to combine individual operations 8545 into a single RPC request. The client interprets each of the 8546 operations in turn. If an operation is executed by the client and 8547 the status of that operation is NFS4_OK, then the next operation in 8548 the CB_COMPOUND procedure is executed. The client continues this 8549 process until there are no more operations to be executed or one of 8550 the operations has a status value other than NFS4_OK. 8552 ERRORS 8554 All errors defined in the protocol 8556 Draft Specification NFS version 4 Protocol February 2000 8558 15.2.1. Operation 3: CB_GETATTR - Get Attributes 8560 SYNOPSIS 8562 fh, attrbits -> attrbits, attrvals 8564 ARGUMENT 8566 struct CB_GETATTR4args { 8567 nfs_fh4 fh; 8568 bitmap4 attr_request; 8569 }; 8571 RESULT 8573 struct CB_GETATTR4resok { 8574 fattr4 obj_attributes; 8575 }; 8577 union CB_GETATTR4res switch (nfsstat4 status) { 8578 case NFS4_OK: 8579 CB_GETATTR4resok resok4; 8580 default: 8581 void; 8582 }; 8584 DESCRIPTION 8586 The CB_GETATTR operation is used to obtain the attributes modified 8587 by an open delegate to allow the server to respond to GETATTR 8588 requests for a file which is the subject of an open delegation. 8590 If the handle specified is not one for which the client holds a 8591 write open delegation, an NFS4ERR_BADHANDLE error is returned. 8593 IMPLEMENTATION 8595 The client returns attrbits and the associated attribute values 8596 only for attributes that it may change (change, time_modify, 8597 object_size). It may further limit the response to attributes that 8598 it has in fact changed during the scope of the delegation. 8600 Draft Specification NFS version 4 Protocol February 2000 8602 ERRORS 8604 NFS4ERR_BADHANDLE 8605 NFS4ERR_RESOURCE 8607 Draft Specification NFS version 4 Protocol February 2000 8609 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation 8611 SYNOPSIS 8613 stateid, truncate, fh -> status 8615 ARGUMENT 8617 struct CB_RECALL4args { 8618 stateid4 stateid; 8619 bool truncate; 8620 nfs_fh4 fh; 8621 }; 8623 RESULT 8625 struct CB_RECALL4res { 8626 nfsstat4 status; 8627 }; 8629 DESCRIPTION 8631 The CB_RECALL operation is used to begin the process of recalling 8632 an open delegation and returning it to the server. 8634 The truncate flag is used to optimize recall for a file which is 8635 about to be truncated to zero. When it is set, the client is freed 8636 of obligation to propagate modified data for the file to the 8637 server, since this data is irrelevant. 8639 If the handle specified is not one for which the client holds an 8640 open delegation, an NFS4ERR_BADHANDLE error is returned. 8642 If the stateid specified is not one corresponding to an open 8643 delegation for the file specified by the filehandle, an 8644 NFS4ERR_BAD_STATEID is returned. 8646 IMPLEMENTATION 8648 The client should reply to the callback immediately. Replying does 8649 not complete the recall. The recall is not complete until the 8650 delegation is returned using a DELEGRETURN. 8652 Draft Specification NFS version 4 Protocol February 2000 8654 ERRORS 8656 NFS4ERR_BADHANDLE 8657 NFS4ERR_BAD_STATEID 8658 NFS4ERR_RESOURCE 8660 Draft Specification NFS version 4 Protocol February 2000 8662 16. Security Considerations 8664 The major security feature to consider is the authentication of the 8665 user making the request of NFS service. Consideration should also be 8666 given to the integrity and privacy of this NFS request. These 8667 specific issues are discussed as part of the section on "RPC and 8668 Security Flavor". 8670 Draft Specification NFS version 4 Protocol February 2000 8672 17. IANA Considerations 8674 17.1. Named Attribute Definition 8676 The NFS version 4 protocol provides for the association of named 8677 attributes to files. The name space identifiers for these attributes 8678 are defined as string names. The protocol does not define the 8679 specific assignment of the name space for these file attributes; the 8680 application developer or system vendor is allowed to define the 8681 attribute, its semantics, and the associated name. Even though this 8682 name space will not be specifically controlled to prevent collisions, 8683 the application developer or system vendor is strongly encouraged to 8684 provide the name assignment and associated semantics for attributes 8685 via an information RFC. This will provide for interoperability where 8686 common interests exist. 8688 Draft Specification NFS version 4 Protocol February 2000 8690 18. RPC definition file 8692 /* 8693 * Copyright (C) The Internet Society (1998,2000). 8694 * All Rights Reserved. 8695 */ 8697 /* 8698 * nfs4_prot.x 8699 * 8700 */ 8702 %#pragma ident "@(#)nfs4_prot.x 1.92 00/02/14" 8704 /* 8705 * Basic typedefs for RFC 1832 data type definitions 8706 */ 8707 typedef int int32_t; 8708 typedef unsigned int uint32_t; 8709 typedef hyper int64_t; 8710 typedef unsigned hyper uint64_t; 8712 /* 8713 * Sizes 8714 */ 8715 const NFS4_FHSIZE = 128; 8716 const NFS4_VERIFIER_SIZE = 8; 8718 /* 8719 * File types 8720 */ 8721 enum nfs_ftype4 { 8722 NF4REG = 1, /* Regular File */ 8723 NF4DIR = 2, /* Directory */ 8724 NF4BLK = 3, /* Special File - block device */ 8725 NF4CHR = 4, /* Special File - character device */ 8726 NF4LNK = 5, /* Symbolic Link */ 8727 NF4SOCK = 6, /* Special File - socket */ 8728 NF4FIFO = 7, /* Special File - fifo */ 8729 NF4ATTRDIR = 8, /* Attribute Directory */ 8730 NF4NAMEDATTR = 9 /* Named Attribute */ 8731 }; 8733 /* 8734 * Error status 8735 */ 8736 enum nfsstat4 { 8737 NFS4_OK = 0, 8739 Draft Specification NFS version 4 Protocol February 2000 8741 NFS4ERR_PERM = 1, 8742 NFS4ERR_NOENT = 2, 8743 NFS4ERR_IO = 5, 8744 NFS4ERR_NXIO = 6, 8745 NFS4ERR_ACCES = 13, 8746 NFS4ERR_EXIST = 17, 8747 NFS4ERR_XDEV = 18, 8748 NFS4ERR_NODEV = 19, 8749 NFS4ERR_NOTDIR = 20, 8750 NFS4ERR_ISDIR = 21, 8751 NFS4ERR_INVAL = 22, 8752 NFS4ERR_FBIG = 27, 8753 NFS4ERR_NOSPC = 28, 8754 NFS4ERR_ROFS = 30, 8755 NFS4ERR_MLINK = 31, 8756 NFS4ERR_NAMETOOLONG = 63, 8757 NFS4ERR_NOTEMPTY = 66, 8758 NFS4ERR_DQUOT = 69, 8759 NFS4ERR_STALE = 70, 8760 NFS4ERR_BADHANDLE = 10001, 8761 NFS4ERR_NOT_SYNC = 10002, 8762 NFS4ERR_BAD_COOKIE = 10003, 8763 NFS4ERR_NOTSUPP = 10004, 8764 NFS4ERR_TOOSMALL = 10005, 8765 NFS4ERR_SERVERFAULT = 10006, 8766 NFS4ERR_BADTYPE = 10007, 8767 NFS4ERR_DELAY = 10008, 8768 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 8769 NFS4ERR_DENIED = 10010,/* lock unavailable */ 8770 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 8771 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 8772 NFS4ERR_GRACE = 10013,/* in grace period */ 8773 NFS4ERR_FHEXPIRED = 10014,/* file handle expired */ 8774 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 8775 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 8776 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 8777 NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ 8778 NFS4ERR_MOVED = 10019,/* filesystem relocated */ 8779 NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */ 8780 NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */ 8781 NFS4ERR_STALE_CLIENTID = 10022, 8782 NFS4ERR_STALE_STATEID = 10023, 8783 NFS4ERR_OLD_STATEID = 10024, 8784 NFS4ERR_BAD_STATEID = 10025, 8785 NFS4ERR_BAD_SEQID = 10026, 8786 NFS4ERR_NOT_SAME = 10027,/* verify - attrs not same */ 8787 NFS4ERR_LOCK_RANGE = 10028, 8788 NFS4ERR_SYMLINK = 10029, 8790 Draft Specification NFS version 4 Protocol February 2000 8792 NFS4ERR_READDIR_NOSPC = 10030, 8793 NFS4ERR_LEASE_MOVED = 10031 8794 }; 8796 /* 8797 * Basic data types 8798 */ 8799 typedef uint32_t bitmap4<>; 8800 typedef uint64_t offset4; 8801 typedef uint32_t count4; 8802 typedef uint64_t length4; 8803 typedef uint64_t clientid4; 8804 typedef uint64_t stateid4; 8805 typedef uint32_t seqid4; 8806 typedef opaque utf8string<>; 8807 typedef utf8string component4; 8808 typedef component4 pathname4<>; 8809 typedef uint64_t nfs_lockid4; 8810 typedef uint64_t nfs_cookie4; 8811 typedef utf8string linktext4; 8812 typedef opaque sec_oid4<>; 8813 typedef uint32_t qop4; 8814 typedef uint32_t mode4; 8815 typedef uint64_t changeid4; 8816 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 8818 /* 8819 * Timeval 8820 */ 8821 struct nfstime4 { 8822 int64_t seconds; 8823 uint32_t nseconds; 8824 }; 8826 enum time_how4 { 8827 SET_TO_SERVER_TIME4 = 0, 8828 SET_TO_CLIENT_TIME4 = 1 8829 }; 8831 union settime4 switch (time_how4 set_it) { 8832 case SET_TO_CLIENT_TIME4: 8833 nfstime4 time; 8834 default: 8835 void; 8836 }; 8838 /* 8839 * File access handle 8841 Draft Specification NFS version 4 Protocol February 2000 8843 */ 8844 typedef opaque nfs_fh4; 8846 /* 8847 * File attribute definitions 8848 */ 8850 /* 8851 * FSID structure for major/minor 8852 */ 8853 struct fsid4 { 8854 uint64_t major; 8855 uint64_t minor; 8856 }; 8858 /* 8859 * Filesystem locations attribute for relocation/migration 8860 */ 8861 struct fs_location4 { 8862 utf8string server<>; 8863 pathname4 rootpath; 8864 }; 8866 struct fs_locations4 { 8867 pathname4 fs_root; 8868 fs_location4 locations<>; 8869 }; 8871 /* 8872 * Various Access Control Entry definitions 8873 */ 8875 /* 8876 * Mask that indicates which Access Control Entries are supported. 8877 * Values for the fattr4_aclsupport attribute. 8878 */ 8879 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 8880 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 8881 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 8882 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 8884 typedef uint32_t acetype4; 8886 /* 8887 * acetype4 values, others can be added as needed. 8888 */ 8890 Draft Specification NFS version 4 Protocol February 2000 8892 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 8893 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 8894 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 8895 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 8897 /* 8898 * ACE flag 8899 */ 8900 typedef uint32_t aceflag4; 8902 /* 8903 * ACE flag values 8904 */ 8905 const ACE4_FILE_INHERIT_ACE = 0x00000001; 8906 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 8907 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 8908 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 8909 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 8910 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 8911 const ACE4_IDENTIFIER_GROUP = 0x00000040; 8913 /* 8914 * ACE mask 8915 */ 8916 typedef uint32_t acemask4; 8918 /* 8919 * ACE mask values 8920 */ 8921 const ACE4_READ_DATA = 0x00000001; 8922 const ACE4_LIST_DIRECTORY = 0x00000001; 8923 const ACE4_WRITE_DATA = 0x00000002; 8924 const ACE4_ADD_FILE = 0x00000002; 8925 const ACE4_APPEND_DATA = 0x00000004; 8926 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 8927 const ACE4_READ_NAMED_ATTRS = 0x00000008; 8928 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 8929 const ACE4_EXECUTE = 0x00000020; 8930 const ACE4_DELETE_CHILD = 0x00000040; 8931 const ACE4_READ_ATTRIBUTES = 0x00000080; 8932 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 8934 const ACE4_DELETE = 0x00010000; 8935 const ACE4_READ_ACL = 0x00020000; 8936 const ACE4_WRITE_ACL = 0x00040000; 8937 const ACE4_WRITE_OWNER = 0x00080000; 8939 Draft Specification NFS version 4 Protocol February 2000 8941 const ACE4_SYNCHRONIZE = 0x00100000; 8943 /* 8944 * ACE4_GENERIC_READ -- defined as combination of 8945 * ACE4_READ_ACL | 8946 * ACE4_READ_DATA | 8947 * ACE4_READ_ATTRIBUTES | 8948 * ACE4_SYNCHRONIZE 8949 */ 8951 const ACE4_GENERIC_READ = 0x00120081; 8953 /* 8954 * ACE4_GENERIC_WRITE -- defined as combination of 8955 * ACE4_READ_ACL | 8956 * ACE4_WRITE_DATA | 8957 * ACE4_WRITE_ATTRIBUTES | 8958 * ACE4_WRITE_ACL | 8959 * ACE4_APPEND_DATA | 8960 * ACE4_SYNCHRONIZE 8961 */ 8962 const ACE4_GENERIC_WRITE = 0x00160102; 8964 /* 8965 * ACE4_GENERIC_EXECUTE -- defined as combination of 8966 * ACE4_READ_ACL 8967 * ACE4_READ_ATTRIBUTES 8968 * ACE4_EXECUTE 8969 * ACE4_SYNCHRONIZE 8970 */ 8971 const ACE4_GENERIC_EXECUTE = 0x001200A0; 8973 /* 8974 * Access Control Entry definition 8975 */ 8976 struct nfsace4 { 8977 acetype4 type; 8978 aceflag4 flag; 8979 acemask4 access_mask; 8980 utf8string who; 8981 }; 8983 /* 8984 * Special data/attribute associated with 8985 * file types NF4BLK and NF4CHR. 8986 */ 8988 Draft Specification NFS version 4 Protocol February 2000 8990 struct specdata4 { 8991 uint32_t specdata1; 8992 uint32_t specdata2; 8993 }; 8995 /* 8996 * Values for fattr4_fh_expire_type 8997 */ 8998 const FH4_PERSISTENT = 0x00000000; 8999 const FH4_NOEXPIRE_WITH_OPEN = 0x00000001; 9000 const FH4_VOLATILE_ANY = 0x00000002; 9001 const FH4_VOL_MIGRATION = 0x00000004; 9002 const FH4_VOL_RENAME = 0x00000008; 9004 typedef bitmap4 fattr4_supported_attrs; 9005 typedef nfs_ftype4 fattr4_type; 9006 typedef uint32_t fattr4_fh_expire_type; 9007 typedef changeid4 fattr4_change; 9008 typedef uint64_t fattr4_size; 9009 typedef bool fattr4_link_support; 9010 typedef bool fattr4_symlink_support; 9011 typedef bool fattr4_named_attr; 9012 typedef fsid4 fattr4_fsid; 9013 typedef bool fattr4_unique_handles; 9014 typedef uint32_t fattr4_lease_time; 9015 typedef nfsstat4 fattr4_rdattr_error; 9017 typedef nfsace4 fattr4_acl<>; 9018 typedef uint32_t fattr4_aclsupport; 9019 typedef bool fattr4_archive; 9020 typedef bool fattr4_cansettime; 9021 typedef bool fattr4_case_insensitive; 9022 typedef bool fattr4_case_preserving; 9023 typedef bool fattr4_chown_restricted; 9024 typedef uint64_t fattr4_fileid; 9025 typedef uint64_t fattr4_files_avail; 9026 typedef nfs_fh4 fattr4_filehandle; 9027 typedef uint64_t fattr4_files_free; 9028 typedef uint64_t fattr4_files_total; 9029 typedef fs_locations4 fattr4_fs_locations; 9030 typedef bool fattr4_hidden; 9031 typedef bool fattr4_homogeneous; 9032 typedef uint64_t fattr4_maxfilesize; 9033 typedef uint32_t fattr4_maxlink; 9034 typedef uint32_t fattr4_maxname; 9035 typedef uint64_t fattr4_maxread; 9036 typedef uint64_t fattr4_maxwrite; 9038 Draft Specification NFS version 4 Protocol February 2000 9040 typedef utf8string fattr4_mimetype; 9041 typedef mode4 fattr4_mode; 9042 typedef bool fattr4_no_trunc; 9043 typedef uint32_t fattr4_numlinks; 9044 typedef utf8string fattr4_owner; 9045 typedef utf8string fattr4_owner_group; 9046 typedef uint64_t fattr4_quota_hard; 9047 typedef uint64_t fattr4_quota_soft; 9048 typedef uint64_t fattr4_quota_used; 9049 typedef specdata4 fattr4_rawdev; 9050 typedef uint64_t fattr4_space_avail; 9051 typedef uint64_t fattr4_space_free; 9052 typedef uint64_t fattr4_space_total; 9053 typedef uint64_t fattr4_space_used; 9054 typedef bool fattr4_system; 9055 typedef nfstime4 fattr4_time_access; 9056 typedef settime4 fattr4_time_access_set; 9057 typedef nfstime4 fattr4_time_backup; 9058 typedef nfstime4 fattr4_time_create; 9059 typedef nfstime4 fattr4_time_delta; 9060 typedef nfstime4 fattr4_time_metadata; 9061 typedef nfstime4 fattr4_time_modify; 9062 typedef settime4 fattr4_time_modify_set; 9064 /* 9065 * Mandatory Attributes 9066 */ 9067 const FATTR4_SUPPORTED_ATTRS = 0; 9068 const FATTR4_TYPE = 1; 9069 const FATTR4_FH_EXPIRE_TYPE = 2; 9070 const FATTR4_CHANGE = 3; 9071 const FATTR4_SIZE = 4; 9072 const FATTR4_LINK_SUPPORT = 5; 9073 const FATTR4_SYMLINK_SUPPORT = 6; 9074 const FATTR4_NAMED_ATTR = 7; 9075 const FATTR4_FSID = 8; 9076 const FATTR4_UNIQUE_HANDLES = 9; 9077 const FATTR4_LEASE_TIME = 10; 9078 const FATTR4_RDATTR_ERROR = 11; 9080 /* 9081 * Recommended Attributes 9082 */ 9083 const FATTR4_ACL = 12; 9084 const FATTR4_ACLSUPPORT = 13; 9085 const FATTR4_ARCHIVE = 14; 9086 const FATTR4_CANSETTIME = 15; 9088 Draft Specification NFS version 4 Protocol February 2000 9090 const FATTR4_CASE_INSENSITIVE = 16; 9091 const FATTR4_CASE_PRESERVING = 17; 9092 const FATTR4_CHOWN_RESTRICTED = 18; 9093 const FATTR4_FILEHANDLE = 19; 9094 const FATTR4_FILEID = 20; 9095 const FATTR4_FILES_AVAIL = 21; 9096 const FATTR4_FILES_FREE = 22; 9097 const FATTR4_FILES_TOTAL = 23; 9098 const FATTR4_FS_LOCATIONS = 24; 9099 const FATTR4_HIDDEN = 25; 9100 const FATTR4_HOMOGENEOUS = 26; 9101 const FATTR4_MAXFILESIZE = 27; 9102 const FATTR4_MAXLINK = 28; 9103 const FATTR4_MAXNAME = 29; 9104 const FATTR4_MAXREAD = 30; 9105 const FATTR4_MAXWRITE = 31; 9106 const FATTR4_MIMETYPE = 32; 9107 const FATTR4_MODE = 33; 9108 const FATTR4_NO_TRUNC = 34; 9109 const FATTR4_NUMLINKS = 35; 9110 const FATTR4_OWNER = 36; 9111 const FATTR4_OWNER_GROUP = 37; 9112 const FATTR4_QUOTA_HARD = 38; 9113 const FATTR4_QUOTA_SOFT = 39; 9114 const FATTR4_QUOTA_USED = 40; 9115 const FATTR4_RAWDEV = 41; 9116 const FATTR4_SPACE_AVAIL = 42; 9117 const FATTR4_SPACE_FREE = 43; 9118 const FATTR4_SPACE_TOTAL = 44; 9119 const FATTR4_SPACE_USED = 45; 9120 const FATTR4_SYSTEM = 46; 9121 const FATTR4_TIME_ACCESS = 47; 9122 const FATTR4_TIME_ACCESS_SET = 48; 9123 const FATTR4_TIME_BACKUP = 49; 9124 const FATTR4_TIME_CREATE = 50; 9125 const FATTR4_TIME_DELTA = 51; 9126 const FATTR4_TIME_METADATA = 52; 9127 const FATTR4_TIME_MODIFY = 53; 9128 const FATTR4_TIME_MODIFY_SET = 54; 9130 typedef opaque attrlist4<>; 9132 /* 9133 * File attribute container 9134 */ 9135 struct fattr4 { 9136 bitmap4 attrmask; 9138 Draft Specification NFS version 4 Protocol February 2000 9140 attrlist4 attr_vals; 9141 }; 9143 /* 9144 * Change info for the client 9145 */ 9146 struct change_info4 { 9147 bool atomic; 9148 changeid4 before; 9149 changeid4 after; 9150 }; 9152 struct clientaddr4 { 9153 /* see struct rpcb in RFC 1833 */ 9154 string r_netid<>; /* network id */ 9155 string r_addr<>; /* universal address */ 9156 }; 9158 /* 9159 * Callback program info as provided by the client 9160 */ 9161 struct cb_client4 { 9162 unsigned int cb_program; 9163 clientaddr4 cb_location; 9164 }; 9166 /* 9167 * Client ID 9168 */ 9169 struct nfs_client_id4 { 9170 verifier4 verifier; 9171 opaque id<>; 9172 }; 9174 struct nfs_lockowner4 { 9175 clientid4 clientid; 9176 opaque owner<>; 9177 }; 9179 enum nfs_lock_type4 { 9180 READ_LT = 1, 9181 WRITE_LT = 2, 9182 READW_LT = 3, /* blocking read */ 9183 WRITEW_LT = 4 /* blocking write */ 9184 }; 9186 /* 9187 * ACCESS: Check access permission 9189 Draft Specification NFS version 4 Protocol February 2000 9191 */ 9192 const ACCESS4_READ = 0x00000001; 9193 const ACCESS4_LOOKUP = 0x00000002; 9194 const ACCESS4_MODIFY = 0x00000004; 9195 const ACCESS4_EXTEND = 0x00000008; 9196 const ACCESS4_DELETE = 0x00000010; 9197 const ACCESS4_EXECUTE = 0x00000020; 9199 struct ACCESS4args { 9200 /* CURRENT_FH: object */ 9201 uint32_t access; 9202 }; 9204 struct ACCESS4resok { 9205 uint32_t supported; 9206 uint32_t access; 9207 }; 9209 union ACCESS4res switch (nfsstat4 status) { 9210 case NFS4_OK: 9211 ACCESS4resok resok4; 9212 default: 9213 void; 9214 }; 9216 /* 9217 * CLOSE: Close a file and release share locks 9218 */ 9219 struct CLOSE4args { 9220 /* CURRENT_FH: object */ 9221 seqid4 seqid; 9222 stateid4 stateid; 9223 }; 9225 union CLOSE4res switch (nfsstat4 status) { 9226 case NFS4_OK: 9227 stateid4 stateid; 9228 default: 9229 void; 9230 }; 9232 /* 9233 * COMMIT: Commit cached data on server to stable storage 9234 */ 9235 struct COMMIT4args { 9236 /* CURRENT_FH: file */ 9237 offset4 offset; 9238 count4 count; 9240 Draft Specification NFS version 4 Protocol February 2000 9242 }; 9244 struct COMMIT4resok { 9245 verifier4 writeverf; 9246 }; 9248 union COMMIT4res switch (nfsstat4 status) { 9249 case NFS4_OK: 9250 COMMIT4resok resok4; 9251 default: 9252 void; 9253 }; 9255 /* 9256 * CREATE: Create a file 9257 */ 9258 union createtype4 switch (nfs_ftype4 type) { 9259 case NF4LNK: 9260 linktext4 linkdata; 9261 case NF4BLK: 9262 case NF4CHR: 9263 specdata4 devdata; 9264 case NF4SOCK: 9265 case NF4FIFO: 9266 case NF4DIR: 9267 void; 9268 }; 9270 struct CREATE4args { 9271 /* CURRENT_FH: directory for creation */ 9272 component4 objname; 9273 createtype4 objtype; 9274 }; 9276 struct CREATE4resok { 9277 change_info4 cinfo; 9278 }; 9280 union CREATE4res switch (nfsstat4 status) { 9281 case NFS4_OK: 9282 CREATE4resok resok4; 9283 default: 9284 void; 9285 }; 9287 /* 9288 * DELEGPURGE: Purge Delegations Awaiting Recovery 9290 Draft Specification NFS version 4 Protocol February 2000 9292 */ 9293 struct DELEGPURGE4args { 9294 clientid4 clientid; 9295 }; 9297 struct DELEGPURGE4res { 9298 nfsstat4 status; 9299 }; 9301 /* 9302 * DELEGRETURN: Return a delegation 9303 */ 9304 struct DELEGRETURN4args { 9305 stateid4 stateid; 9306 }; 9308 struct DELEGRETURN4res { 9309 nfsstat4 status; 9310 }; 9312 /* 9313 * GETATTR: Get file attributes 9314 */ 9315 struct GETATTR4args { 9316 /* CURRENT_FH: directory or file */ 9317 bitmap4 attr_request; 9318 }; 9320 struct GETATTR4resok { 9321 fattr4 obj_attributes; 9322 }; 9324 union GETATTR4res switch (nfsstat4 status) { 9325 case NFS4_OK: 9326 GETATTR4resok resok4; 9327 default: 9328 void; 9329 }; 9331 /* 9332 * GETFH: Get current filehandle 9333 */ 9334 struct GETFH4resok { 9335 nfs_fh4 object; 9336 }; 9338 union GETFH4res switch (nfsstat4 status) { 9339 case NFS4_OK: 9341 Draft Specification NFS version 4 Protocol February 2000 9343 GETFH4resok resok4; 9344 default: 9345 void; 9346 }; 9348 /* 9349 * LINK: Create link to an object 9350 */ 9351 struct LINK4args { 9352 /* SAVED_FH: source object */ 9353 /* CURRENT_FH: target directory */ 9354 component4 newname; 9355 }; 9357 struct LINK4resok { 9358 change_info4 cinfo; 9359 }; 9361 union LINK4res switch (nfsstat4 status) { 9362 case NFS4_OK: 9363 LINK4resok resok4; 9364 default: 9365 void; 9366 }; 9368 /* 9369 * LOCK/LOCKT/LOCKU: Record lock management 9370 */ 9371 struct LOCK4args { 9372 /* CURRENT_FH: file */ 9373 nfs_lock_type4 locktype; 9374 seqid4 seqid; 9375 bool reclaim; 9376 stateid4 stateid; 9377 offset4 offset; 9378 length4 length; 9379 }; 9381 struct LOCK4denied { 9382 nfs_lockowner4 owner; 9383 offset4 offset; 9384 length4 length; 9385 }; 9387 union LOCK4res switch (nfsstat4 status) { 9388 case NFS4_OK: 9389 stateid4 stateid; 9390 case NFS4ERR_DENIED: 9392 Draft Specification NFS version 4 Protocol February 2000 9394 LOCK4denied denied; 9395 default: 9396 void; 9397 }; 9399 struct LOCKT4args { 9400 /* CURRENT_FH: file */ 9401 nfs_lock_type4 locktype; 9402 nfs_lockowner4 owner; 9403 offset4 offset; 9404 length4 length; 9405 }; 9407 union LOCKT4res switch (nfsstat4 status) { 9408 case NFS4ERR_DENIED: 9409 LOCK4denied denied; 9410 case NFS4_OK: 9411 void; 9412 default: 9413 void; 9414 }; 9416 struct LOCKU4args { 9417 /* CURRENT_FH: file */ 9418 nfs_lock_type4 type; 9419 seqid4 seqid; 9420 stateid4 stateid; 9421 offset4 offset; 9422 length4 length; 9423 }; 9425 union LOCKU4res switch (nfsstat4 status) { 9426 case NFS4_OK: 9427 stateid4 stateid; 9428 default: 9429 void; 9430 }; 9432 /* 9433 * LOOKUP: Lookup filename 9434 */ 9435 struct LOOKUP4args { 9436 /* CURRENT_FH: directory */ 9437 pathname4 path; 9438 }; 9440 struct LOOKUP4res { 9441 /* CURRENT_FH: object */ 9443 Draft Specification NFS version 4 Protocol February 2000 9445 nfsstat4 status; 9446 }; 9448 /* 9449 * LOOKUPP: Lookup parent directory 9450 */ 9451 struct LOOKUPP4res { 9452 /* CURRENT_FH: directory */ 9453 nfsstat4 status; 9454 }; 9456 /* 9457 * NVERIFY: Verify attributes different 9458 */ 9459 struct NVERIFY4args { 9460 /* CURRENT_FH: object */ 9461 bitmap4 attr_request; 9462 fattr4 obj_attributes; 9463 }; 9465 struct NVERIFY4res { 9466 nfsstat4 status; 9467 }; 9469 /* 9470 * Various definitions for OPEN 9471 */ 9472 enum createmode4 { 9473 UNCHECKED4 = 0, 9474 GUARDED4 = 1, 9475 EXCLUSIVE4 = 2 9476 }; 9478 union createhow4 switch (createmode4 mode) { 9479 case UNCHECKED4: 9480 case GUARDED4: 9481 fattr4 createattrs; 9482 case EXCLUSIVE4: 9483 verifier4 createverf; 9484 }; 9486 enum opentype4 { 9487 OPEN4_NOCREATE = 0, 9488 OPEN4_CREATE = 1 9489 }; 9491 union openflag4 switch (opentype4 opentype) { 9492 case OPEN4_CREATE: 9494 Draft Specification NFS version 4 Protocol February 2000 9496 createhow4 how; 9497 default: 9498 void; 9499 }; 9501 /* Next definitions used for OPEN delegation */ 9502 enum limit_by4 { 9503 NFS_LIMIT_SIZE = 1, 9504 NFS_LIMIT_BLOCKS = 2 9505 /* others as needed */ 9506 }; 9508 struct nfs_modified_limit4 { 9509 uint32_t num_blocks; 9510 uint32_t bytes_per_block; 9511 }; 9513 union nfs_space_limit4 switch (limit_by4 limitby) { 9514 /* limit specified as file size */ 9515 case NFS_LIMIT_SIZE: 9516 uint64_t filesize; 9517 /* limit specified by number of blocks */ 9518 case NFS_LIMIT_BLOCKS: 9519 nfs_modified_limit4 mod_blocks; 9520 } ; 9522 /* 9523 * Share Access and Deny constants for open argument 9524 */ 9525 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 9526 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 9527 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 9529 const OPEN4_SHARE_DENY_NONE = 0x00000000; 9530 const OPEN4_SHARE_DENY_READ = 0x00000001; 9531 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 9532 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 9534 enum open_delegation_type4 { 9535 OPEN_DELEGATE_NONE = 0, 9536 OPEN_DELEGATE_READ = 1, 9537 OPEN_DELEGATE_WRITE = 2 9538 }; 9540 enum open_claim_type4 { 9541 CLAIM_NULL = 0, 9542 CLAIM_PREVIOUS = 1, 9543 CLAIM_DELEGATE_CUR = 2, 9545 Draft Specification NFS version 4 Protocol February 2000 9547 CLAIM_DELEGATE_PREV = 3 9548 }; 9550 struct open_claim_delegate_cur4 { 9551 pathname4 file; 9552 stateid4 delegate_stateid; 9553 }; 9555 union open_claim4 switch (open_claim_type4 claim) { 9556 /* 9557 * No special rights to file. Ordinary OPEN of the specified file. 9558 */ 9559 case CLAIM_NULL: 9560 /* CURRENT_FH: directory */ 9561 pathname4 file; 9563 /* 9564 * Right to the file established by an open previous to server 9565 * reboot. File identified by filehandle obtained at that time 9566 * rather than by name. 9567 */ 9568 case CLAIM_PREVIOUS: 9569 /* CURRENT_FH: file being reclaimed */ 9570 uint32_t delegate_type; 9572 /* 9573 * Right to file based on a delegation granted by the server. 9574 * File is specified by name. 9575 */ 9576 case CLAIM_DELEGATE_CUR: 9577 /* CURRENT_FH: directory */ 9578 open_claim_delegate_cur4 delegate_cur_info; 9580 /* Right to file based on a delegation granted to a previous boot 9581 * instance of the client. File is specified by name. 9582 */ 9583 case CLAIM_DELEGATE_PREV: 9584 /* CURRENT_FH: directory */ 9585 pathname4 file_delegate_prev; 9586 }; 9588 /* 9589 * OPEN: Open a file, potentially receiving an open delegation 9590 */ 9591 struct OPEN4args { 9592 open_claim4 claim; 9593 openflag4 openhow; 9594 nfs_lockowner4 owner; 9596 Draft Specification NFS version 4 Protocol February 2000 9598 seqid4 seqid; 9599 uint32_t share_access; 9600 uint32_t share_deny; 9601 }; 9603 struct open_read_delegation4 { 9604 stateid4 stateid; /* Stateid for delegation*/ 9605 bool recall; /* Pre-recalled flag for 9606 delegations obtained 9607 by reclaim 9608 (CLAIM_PREVIOUS) */ 9609 nfsace4 permissions; /* Defines users who don't 9610 need an ACCESS call to 9611 open for read */ 9612 }; 9614 struct open_write_delegation4 { 9615 stateid4 stateid; /* Stateid for delegation 9616 be flushed to the server 9617 on close. */ 9618 bool recall; /* Pre-recalled flag for 9619 delegations obtained 9620 by reclaim 9621 (CLAIM_PREVIOUS) */ 9622 nfs_space_limit4 space_limit; /* Defines condition that 9623 the client must check to 9624 determine whether the 9625 file needs to be flushed 9626 to the server on close. 9627 */ 9628 nfsace4 permissions; /* Defines users who don't 9629 need an ACCESS call as 9630 part of a delegated 9631 open. */ 9632 }; 9634 union open_delegation4 9635 switch (open_delegation_type4 delegation_type) { 9636 case OPEN_DELEGATE_NONE: 9637 void; 9638 case OPEN_DELEGATE_READ: 9639 open_read_delegation4 read; 9640 case OPEN_DELEGATE_WRITE: 9641 open_write_delegation4 write; 9642 }; 9644 /* 9645 * Result flags 9647 Draft Specification NFS version 4 Protocol February 2000 9649 */ 9650 /* Mandatory locking is in effect for this file. */ 9651 const OPEN4_RESULT_MLOCK = 0x00000001; 9652 /* Client must confirm open */ 9653 const OPEN4_RESULT_CONFIRM = 0x00000002; 9655 struct OPEN4resok { 9656 stateid4 stateid; /* Stateid for open */ 9657 change_info4 cinfo; /* Directory Change Info */ 9658 uint32_t rflags; /* Result flags */ 9659 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 9660 open_delegation4 delegation; /* Info on any open 9661 delegation */ 9662 }; 9664 union OPEN4res switch (nfsstat4 status) { 9665 case NFS4_OK: 9666 /* CURRENT_FH: opened file */ 9667 OPEN4resok result; 9668 default: 9669 void; 9670 }; 9672 /* 9673 * OPENATTR: open named attributes directory 9674 */ 9675 struct OPENATTR4res { 9676 /* CURRENT_FH: name attr directory*/ 9677 nfsstat4 status; 9678 }; 9680 /* 9681 * OPEN_CONFIRM: confirm the open 9682 */ 9683 struct OPEN_CONFIRM4args { 9684 /* CURRENT_FH: opened file */ 9685 seqid4 seqid; 9686 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 9687 }; 9689 struct OPEN_CONFIRM4resok { 9690 stateid4 stateid; 9691 }; 9693 union OPEN_CONFIRM4res switch (nfsstat4 status) { 9694 case NFS4_OK: 9695 OPEN_CONFIRM4resok resok4; 9696 default: 9698 Draft Specification NFS version 4 Protocol February 2000 9700 void; 9701 }; 9703 /* 9704 * OPEN_DOWNGRADE: downgrade the access/deny for a file 9705 */ 9706 struct OPEN_DOWNGRADE4args { 9707 /* CURRENT_FH: opened file */ 9708 stateid4 stateid; 9709 seqid4 seqid; 9710 uint32_t share_access; 9711 uint32_t share_deny; 9712 }; 9714 struct OPEN_DOWNGRADE4resok { 9715 stateid4 stateid; 9716 }; 9718 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 9719 case NFS4_OK: 9720 OPEN_DOWNGRADE4resok resok4; 9721 default: 9722 void; 9723 }; 9725 /* 9726 * PUTFH: Set current filehandle 9727 */ 9728 struct PUTFH4args { 9729 nfs_fh4 object; 9730 }; 9732 struct PUTFH4res { 9733 /* CURRENT_FH: */ 9734 nfsstat4 status; 9735 }; 9737 /* 9738 * PUTPUBFH: Set public filehandle 9739 */ 9740 struct PUTPUBFH4res { 9741 /* CURRENT_FH: public fh */ 9742 nfsstat4 status; 9743 }; 9745 /* 9746 * PUTROOTFH: Set root filehandle 9747 */ 9749 Draft Specification NFS version 4 Protocol February 2000 9751 struct PUTROOTFH4res { 9752 /* CURRENT_FH: root fh */ 9753 nfsstat4 status; 9754 }; 9756 /* 9757 * READ: Read from file 9758 */ 9759 struct READ4args { 9760 /* CURRENT_FH: file */ 9761 stateid4 stateid; 9762 offset4 offset; 9763 count4 count; 9764 }; 9766 struct READ4resok { 9767 bool eof; 9768 opaque data<>; 9769 }; 9771 union READ4res switch (nfsstat4 status) { 9772 case NFS4_OK: 9773 READ4resok resok4; 9774 default: 9775 void; 9776 }; 9778 /* 9779 * READDIR: Read directory 9780 */ 9781 struct READDIR4args { 9782 /* CURRENT_FH: directory */ 9783 nfs_cookie4 cookie; 9784 verifier4 cookieverf; 9785 count4 dircount; 9786 count4 maxcount; 9787 bitmap4 attr_request; 9788 }; 9790 struct entry4 { 9791 nfs_cookie4 cookie; 9792 component4 name; 9793 fattr4 attrs; 9794 entry4 *nextentry; 9795 }; 9797 struct dirlist4 { 9798 entry4 *entries; 9800 Draft Specification NFS version 4 Protocol February 2000 9802 bool eof; 9803 }; 9805 struct READDIR4resok { 9806 verifier4 cookieverf; 9807 dirlist4 reply; 9808 }; 9810 union READDIR4res switch (nfsstat4 status) { 9811 case NFS4_OK: 9812 READDIR4resok resok4; 9813 default: 9814 void; 9815 }; 9817 /* 9818 * READLINK: Read symbolic link 9819 */ 9820 struct READLINK4resok { 9821 linktext4 link; 9822 }; 9824 union READLINK4res switch (nfsstat4 status) { 9825 case NFS4_OK: 9826 READLINK4resok resok4; 9827 default: 9828 void; 9829 }; 9831 /* 9832 * REMOVE: Remove filesystem object 9833 */ 9834 struct REMOVE4args { 9835 /* CURRENT_FH: directory */ 9836 component4 target; 9837 }; 9839 struct REMOVE4resok { 9840 change_info4 cinfo; 9841 }; 9843 union REMOVE4res switch (nfsstat4 status) { 9844 case NFS4_OK: 9845 REMOVE4resok resok4; 9846 default: 9847 void; 9849 Draft Specification NFS version 4 Protocol February 2000 9851 }; 9853 /* 9854 * RENAME: Rename directory entry 9855 */ 9856 struct RENAME4args { 9857 /* SAVED_FH: source directory */ 9858 component4 oldname; 9859 /* CURRENT_FH: target directory */ 9860 component4 newname; 9861 }; 9863 struct RENAME4resok { 9864 change_info4 source_cinfo; 9865 change_info4 target_cinfo; 9866 }; 9868 union RENAME4res switch (nfsstat4 status) { 9869 case NFS4_OK: 9870 RENAME4resok resok4; 9871 default: 9872 void; 9873 }; 9875 /* 9876 * RENEW: Renew a Lease 9877 */ 9878 struct RENEW4args { 9879 stateid4 stateid; 9880 }; 9882 struct RENEW4res { 9883 nfsstat4 status; 9884 }; 9886 /* 9887 * RESTOREFH: Restore saved filehandle 9888 */ 9890 struct RESTOREFH4res { 9891 /* CURRENT_FH: value of saved fh */ 9892 nfsstat4 status; 9893 }; 9895 /* 9896 * SAVEFH: Save current filehandle 9897 */ 9898 struct SAVEFH4res { 9900 Draft Specification NFS version 4 Protocol February 2000 9902 /* SAVED_FH: value of current fh */ 9903 nfsstat4 status; 9904 }; 9906 /* 9907 * SECINFO: Obtain Available Security Mechanisms 9908 */ 9909 struct SECINFO4args { 9910 /* CURRENT_FH: */ 9911 component4 name; 9912 }; 9914 /* 9915 * From RFC 2203 9916 */ 9917 enum rpc_gss_svc_t { 9918 RPC_GSS_SVC_NONE = 1, 9919 RPC_GSS_SVC_INTEGRITY = 2, 9920 RPC_GSS_SVC_PRIVACY = 3 9921 }; 9923 struct rpcsec_gss_info { 9924 sec_oid4 oid; 9925 qop4 qop; 9926 rpc_gss_svc_t service; 9927 }; 9929 struct secinfo4 { 9930 uint32_t flavor; 9931 /* null for AUTH_SYS, AUTH_NONE; 9932 contains rpcsec_gss_info for 9933 RPCSEC_GSS. */ 9934 opaque flavor_info<>; 9935 }; 9937 typedef secinfo4 SECINFO4resok<>; 9939 union SECINFO4res switch (nfsstat4 status) { 9940 case NFS4_OK: 9941 SECINFO4resok resok4; 9942 default: 9943 void; 9944 }; 9946 /* 9947 * SETATTR: Set attributes 9948 */ 9949 struct SETATTR4args { 9951 Draft Specification NFS version 4 Protocol February 2000 9953 /* CURRENT_FH: target object */ 9954 stateid4 stateid; 9955 fattr4 obj_attributes; 9956 }; 9958 struct SETATTR4res { 9959 nfsstat4 status; 9960 bitmap4 attrsset; 9961 }; 9963 /* 9964 * SETCLIENTID 9965 */ 9966 struct SETCLIENTID4args { 9967 nfs_client_id4 client; 9968 cb_client4 callback; 9969 }; 9971 struct SETCLIENTID4resok { 9972 clientid4 clientid; 9973 verifier4 setclientid_confirm; 9974 }; 9976 union SETCLIENTID4res switch (nfsstat4 status) { 9977 case NFS4_OK: 9978 SETCLIENTID4resok resok4; 9979 case NFS4ERR_CLID_INUSE: 9980 clientaddr4 client_using; 9981 default: 9982 void; 9983 }; 9985 struct SETCLIENTID_CONFIRM4args { 9986 verifier4 setclientid_confirm; 9987 }; 9989 struct SETCLIENTID_CONFIRM4res { 9990 nfsstat4 status; 9991 }; 9993 /* 9994 * VERIFY: Verify attributes same 9995 */ 9996 struct VERIFY4args { 9997 /* CURRENT_FH: object */ 9998 bitmap4 attr_request; 9999 fattr4 obj_attributes; 10000 }; 10002 Draft Specification NFS version 4 Protocol February 2000 10004 struct VERIFY4res { 10005 nfsstat4 status; 10006 }; 10008 /* 10009 * WRITE: Write to file 10010 */ 10011 enum stable_how4 { 10012 UNSTABLE4 = 0, 10013 DATA_SYNC4 = 1, 10014 FILE_SYNC4 = 2 10015 }; 10017 struct WRITE4args { 10018 /* CURRENT_FH: file */ 10019 stateid4 stateid; 10020 offset4 offset; 10021 stable_how4 stable; 10022 opaque data<>; 10023 }; 10025 struct WRITE4resok { 10026 count4 count; 10027 stable_how4 committed; 10028 verifier4 writeverf; 10029 }; 10031 union WRITE4res switch (nfsstat4 status) { 10032 case NFS4_OK: 10033 WRITE4resok resok4; 10034 default: 10035 void; 10036 }; 10038 /* 10039 * Operation arrays 10040 */ 10042 enum nfs_opnum4 { 10043 OP_ACCESS = 3, 10044 OP_CLOSE = 4, 10045 OP_COMMIT = 5, 10046 OP_CREATE = 6, 10047 OP_DELEGPURGE = 7, 10048 OP_DELEGRETURN = 8, 10049 OP_GETATTR = 9, 10050 OP_GETFH = 10, 10051 OP_LINK = 11, 10053 Draft Specification NFS version 4 Protocol February 2000 10055 OP_LOCK = 12, 10056 OP_LOCKT = 13, 10057 OP_LOCKU = 14, 10058 OP_LOOKUP = 15, 10059 OP_LOOKUPP = 16, 10060 OP_NVERIFY = 17, 10061 OP_OPEN = 18, 10062 OP_OPENATTR = 19, 10063 OP_OPEN_CONFIRM = 20, 10064 OP_OPEN_DOWNGRADE = 21, 10065 OP_PUTFH = 22, 10066 OP_PUTPUBFH = 23, 10067 OP_PUTROOTFH = 24, 10068 OP_READ = 25, 10069 OP_READDIR = 26, 10070 OP_READLINK = 27, 10071 OP_REMOVE = 28, 10072 OP_RENAME = 29, 10073 OP_RENEW = 30, 10074 OP_RESTOREFH = 31, 10075 OP_SAVEFH = 32, 10076 OP_SECINFO = 33, 10077 OP_SETATTR = 34, 10078 OP_SETCLIENTID = 35, 10079 OP_SETCLIENTID_CONFIRM = 36, 10080 OP_VERIFY = 37, 10081 OP_WRITE = 38 10082 }; 10084 union nfs_argop4 switch (nfs_opnum4 argop) { 10085 case OP_ACCESS: ACCESS4args opaccess; 10086 case OP_CLOSE: CLOSE4args opclose; 10087 case OP_COMMIT: COMMIT4args opcommit; 10088 case OP_CREATE: CREATE4args opcreate; 10089 case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; 10090 case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; 10091 case OP_GETATTR: GETATTR4args opgetattr; 10092 case OP_GETFH: void; 10093 case OP_LINK: LINK4args oplink; 10094 case OP_LOCK: LOCK4args oplock; 10095 case OP_LOCKT: LOCK4args oplockt; 10096 case OP_LOCKU: LOCK4args oplocku; 10097 case OP_LOOKUP: LOOKUP4args oplookup; 10098 case OP_LOOKUPP: void; 10099 case OP_NVERIFY: NVERIFY4args opnverify; 10100 case OP_OPEN: OPEN4args opopen; 10101 case OP_OPENATTR: void; 10102 case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; 10104 Draft Specification NFS version 4 Protocol February 2000 10106 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4args opopen_downgrade; 10107 case OP_PUTFH: PUTFH4args opputfh; 10108 case OP_PUTPUBFH: void; 10109 case OP_PUTROOTFH: void; 10110 case OP_READ: READ4args opread; 10111 case OP_READDIR: READDIR4args opreaddir; 10112 case OP_READLINK: void; 10113 case OP_REMOVE: REMOVE4args opremove; 10114 case OP_RENAME: RENAME4args oprename; 10115 case OP_RENEW: RENEW4args oprenew; 10116 case OP_RESTOREFH: void; 10117 case OP_SAVEFH: void; 10118 case OP_SECINFO: SECINFO4args opsecinfo; 10119 case OP_SETATTR: SETATTR4args opsetattr; 10120 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 10121 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args 10122 opsetclientid_confirm; 10123 case OP_VERIFY: VERIFY4args opverify; 10124 case OP_WRITE: WRITE4args opwrite; 10125 }; 10127 union nfs_resop4 switch (nfs_opnum4 resop){ 10128 case OP_ACCESS: ACCESS4res opaccess; 10129 case OP_CLOSE: CLOSE4res opclose; 10130 case OP_COMMIT: COMMIT4res opcommit; 10131 case OP_CREATE: CREATE4res opcreate; 10132 case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; 10133 case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; 10134 case OP_GETATTR: GETATTR4res opgetattr; 10135 case OP_GETFH: GETFH4res opgetfh; 10136 case OP_LINK: LINK4res oplink; 10137 case OP_LOCK: LOCK4res oplock; 10138 case OP_LOCKT: LOCKT4res oplockt; 10139 case OP_LOCKU: LOCKU4res oplocku; 10140 case OP_LOOKUP: LOOKUP4res oplookup; 10141 case OP_LOOKUPP: LOOKUPP4res oplookupp; 10142 case OP_NVERIFY: NVERIFY4res opnverify; 10143 case OP_OPEN: OPEN4res opopen; 10144 case OP_OPENATTR: OPENATTR4res opopenattr; 10145 case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; 10146 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4res opopen_downgrade; 10147 case OP_PUTFH: PUTFH4res opputfh; 10148 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 10149 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 10150 case OP_READ: READ4res opread; 10151 case OP_READDIR: READDIR4res opreaddir; 10152 case OP_READLINK: READLINK4res opreadlink; 10153 case OP_REMOVE: REMOVE4res opremove; 10155 Draft Specification NFS version 4 Protocol February 2000 10157 case OP_RENAME: RENAME4res oprename; 10158 case OP_RENEW: RENEW4res oprenew; 10159 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 10160 case OP_SAVEFH: SAVEFH4res opsavefh; 10161 case OP_SECINFO: SECINFO4res opsecinfo; 10162 case OP_SETATTR: SETATTR4res opsetattr; 10163 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 10164 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4res 10165 opsetclientid_confirm; 10166 case OP_VERIFY: VERIFY4res opverify; 10167 case OP_WRITE: WRITE4res opwrite; 10168 }; 10170 struct COMPOUND4args { 10171 utf8string tag; 10172 uint32_t minorversion; 10173 nfs_argop4 argarray<>; 10174 }; 10176 struct COMPOUND4res { 10177 nfsstat4 status; 10178 utf8string tag; 10179 nfs_resop4 resarray<>; 10180 }; 10182 /* 10183 * Remote file service routines 10184 */ 10185 program NFS4_PROGRAM { 10186 version NFS_V4 { 10187 void 10188 NFSPROC4_NULL(void) = 0; 10190 COMPOUND4res 10191 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 10193 } = 4; 10194 } = 100003; 10196 /* 10197 * NFS4 Callback Procedure Definitions and Program 10198 */ 10200 /* 10201 * CB_GETATTR: Get Current Attributes 10202 */ 10204 Draft Specification NFS version 4 Protocol February 2000 10206 struct CB_GETATTR4args { 10207 nfs_fh4 fh; 10208 bitmap4 attr_request; 10209 }; 10211 struct CB_GETATTR4resok { 10212 fattr4 obj_attributes; 10213 }; 10215 union CB_GETATTR4res switch (nfsstat4 status) { 10216 case NFS4_OK: 10217 CB_GETATTR4resok resok4; 10218 default: 10219 void; 10220 }; 10222 /* 10223 * CB_RECALL: Recall an Open Delegation 10224 */ 10225 struct CB_RECALL4args { 10226 stateid4 stateid; 10227 bool truncate; 10228 nfs_fh4 fh; 10229 }; 10231 struct CB_RECALL4res { 10232 nfsstat4 status; 10233 }; 10235 /* 10236 * Various definitions for CB_COMPOUND 10237 */ 10238 enum nfs_cb_opnum4 { 10239 OP_CB_GETATTR = 3, 10240 OP_CB_RECALL = 4 10241 }; 10243 union nfs_cb_argop4 switch (unsigned argop) { 10244 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 10245 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 10246 }; 10248 union nfs_cb_resop4 switch (unsigned resop){ 10249 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 10250 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 10251 }; 10253 struct CB_COMPOUND4args { 10255 Draft Specification NFS version 4 Protocol February 2000 10257 utf8string tag; 10258 uint32_t minorversion; 10259 nfs_cb_argop4 argarray<>; 10260 }; 10262 struct CB_COMPOUND4res { 10263 nfsstat4 status; 10264 utf8string tag; 10265 nfs_cb_resop4 resarray<>; 10266 }; 10268 /* 10269 * Program number is in the transient range since the client 10270 * will assign the exact transient program number and provide 10271 * that to the server via the SETCLIENTID operation. 10272 */ 10273 program NFS4_CALLBACK { 10274 version NFS_CB { 10275 void 10276 CB_NULL(void) = 0; 10277 CB_COMPOUND4res 10278 CB_COMPOUND(CB_COMPOUND4args) = 1; 10279 } = 1; 10280 } = 40000000; 10282 Draft Specification NFS version 4 Protocol February 2000 10284 19. Bibliography 10286 [Gray] 10287 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 10288 for Distributed File Cache Consistency," Proceedings of the Twelfth 10289 Symposium on Operating Systems Principles, p. 202-210, December 1989. 10291 [ISO10646] 10292 "ISO/IEC 10646-1:1993. International Standard -- Information 10293 technology -- Universal Multiple-Octet Coded Character Set (UCS) -- 10294 Part 1: Architecture and Basic Multilingual Plane." 10296 [Juszczak] 10297 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 10298 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 10299 CA, June 1990, pages 53-63. Describes reply cache implementation 10300 that avoids work in the server by handling duplicate requests. More 10301 important, though listed as a side-effect, the reply cache aids in 10302 the avoidance of destructive non-idempotent operation re-application 10303 -- improving correctness. 10305 [Kazar] 10306 Kazar, Michael Leon, "Synchronization and Caching Issues in the 10307 Andrew File System," USENIX Conference Proceedings, USENIX 10308 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 10309 description of the cache consistency scheme in AFS. Contrasted with 10310 other distributed file systems. 10312 [Macklem] 10313 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 10314 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 10315 Association, Berkeley, CA, January 1991. Describes performance work 10316 in tuning the 4.3BSD Reno NFS implementation. Describes performance 10317 improvement (reduced CPU loading) through elimination of data copies. 10319 [Mogul] 10320 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 10321 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 10322 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 10323 lease-based scheme for recovering state of consistency protocol. 10325 Draft Specification NFS version 4 Protocol February 2000 10327 [Nowicki] 10328 Nowicki, Bill, "Transport Issues in the Network File System," ACM 10329 SIGCOMM newsletter Computer Communication Review, April 1989. A 10330 brief description of the basis for the dynamic retransmission work. 10332 [Pawlowski] 10333 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 10334 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 10335 Conf. Proc., (1989) Description of an NFS server implementation for 10336 IBM's MVS operating system. 10338 [RFC1094] 10339 Sun Microsystems, Inc., "NFS: Network File System Protocol 10340 Specification", RFC1094, March 1989. 10342 http://www.ietf.org/rfc/rfc1094.txt 10344 [RFC1345] 10345 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 10346 Rationel Almen Planlaegning, June 1992. 10348 http://www.ietf.org/rfc/rfc1345.txt 10350 [RFC1700] 10351 Reynolds, J., Postel, J., "Assigned Numbers", RFC1700, ISI, October 10352 1994 10354 http://www.ietf.org/rfc/rfc1700.txt 10356 [RFC1813] 10357 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 10358 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 10360 http://www.ietf.org/rfc/rfc1813.txt 10362 [RFC1831] 10363 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 10364 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 10366 http://www.ietf.org/rfc/rfc1831.txt 10368 Draft Specification NFS version 4 Protocol February 2000 10370 [RFC1832] 10371 Srinivasan, R., "XDR: External Data Representation Standard", 10372 RFC1832, Sun Microsystems, Inc., August 1995. 10374 http://www.ietf.org/rfc/rfc1832.txt 10376 [RFC1833] 10377 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 10378 Sun Microsystems, Inc., August 1995. 10380 http://www.ietf.org/rfc/rfc1833.txt 10382 [RFC2025] 10383 Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", RFC2025, 10384 Bell-Northern Research, October 1996. 10386 http://www.ietf.org/rfc/rfc2026.txt 10388 [RFC2054] 10389 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 10390 Microsystems, Inc., October 1996 10392 http://www.ietf.org/rfc/rfc2054.txt 10394 [RFC2055] 10395 Callaghan, B., "WebNFS Server Specification", RFC2055, Sun 10396 Microsystems, Inc., October 1996 10398 http://www.ietf.org/rfc/rfc2055.txt 10400 [RFC2078] 10401 Linn, J., "Generic Security Service Application Program Interface, 10402 Version 2", RFC2078, OpenVision Technologies, January 1997. 10404 http://www.ietf.org/rfc/rfc2078.txt 10406 [RFC2152] 10407 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 10408 RFC2152, Apple Computer, Inc., May 1997 10410 http://www.ietf.org/rfc/rfc2152.txt 10412 Draft Specification NFS version 4 Protocol February 2000 10414 [RFC2203] 10415 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 10416 RFC2203, Sun Microsystems, Inc., August 1995. 10418 http://www.ietf.org/rfc/rfc2203.txt 10420 [RFC2277] 10421 Alvestrand, H., "IETF Policy on Character Sets and Languages", 10422 RFC2277, UNINETT, January 1998. 10424 http://www.ietf.org/rfc/rfc2277.txt 10426 [RFC2279] 10427 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 10428 Alis Technologies, January 1998. 10430 http://www.ietf.org/rfc/rfc2279.txt 10432 [RFC2623] 10433 Eisler, M., "NFS Version 2 and Version 3 Security Issues and the NFS 10434 Protocol's Use of RPCSEC_GSS and Kerberos V5", RFC2623, Sun 10435 Microsystems, June 1999 10437 http://www.ietf.org/rfc/rfc2623.txt 10439 [RFC2624] 10440 Shepler, S., "NFS Version 4 Design Considerations", RFC2624, Sun 10441 Microsystems, June 1999 10443 http://www.ietf.org/rfc/rfc2624.txt 10445 [RFCXXXX] 10446 Eisler, M., "LIPKEY - A Low Infrastructure Public Key Mechanism Using 10447 SPKM", RFCXXXX, Sun Microsystems, December 1999 10449 http://www.ietf.org/internet-drafts/draft-ietf-cat-lipkey-03.txt 10451 [Sandberg] 10452 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 10453 and Implementation of the Sun Network Filesystem," USENIX Conference 10454 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 10455 basic paper describing the SunOS implementation of the NFS version 2 10457 Draft Specification NFS version 4 Protocol February 2000 10459 protocol, and discusses the goals, protocol specification and trade- 10460 offs. 10462 [Srinivasan] 10463 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 10464 Performance of Cache Consistency Protocols", WRL Research Report 10465 89/5, Digital Equipment Corporation Western Research Laboratory, 100 10466 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 10467 the effect of applying a Sprite-like consistency protocol applied to 10468 standard NFS. The issues of recovery in a stateful environment are 10469 covered in [Mogul]. 10471 [Unicode1] 10472 The Unicode Consortium, "The Unicode Standard, Version 3.0", 10473 Addison-Wesley Developers Press, Reading, MA, 2000. ISBN 0-201- 10474 61633-5. 10476 More information available at: http://www.unicode.org/ 10478 [Unicode2] 10479 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 10480 700519, San Jose, CA 95710-0519 USA, September 1999 10482 http://www.unicode.org/unicode/standard/unsupported.html 10484 [XNFS] 10485 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 10486 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 10487 1-85912-184-5, February 1998. 10489 HTML version available: http://www.opengroup.org 10491 Draft Specification NFS version 4 Protocol February 2000 10493 20. Authors 10495 20.1. Editor's Address 10497 Spencer Shepler 10498 Sun Microsystems, Inc. 10499 7808 Moonflower Drive 10500 Austin, Texas 78750 10502 Phone: +1 512-349-9376 10503 E-mail: shepler@eng.sun.com 10505 20.2. Authors' Addresses 10507 Carl Beame 10508 Hummingbird Communications Ltd. 10510 E-mail: beame@bws.com 10512 Brent Callaghan 10513 Sun Microsystems, Inc. 10514 901 San Antonio Road 10515 Palo Alto, CA 94303 10517 Phone: +1 650-786-5067 10518 E-mail: brent.callaghan@eng.sun.com 10520 Mike Eisler 10521 Sun Microsystems, Inc. 10522 5565 Wilson Road 10523 Colorado Springs, CO 80919 10525 Phone: +1 719-599-9026 10526 E-mail: mre@eng.sun.com 10528 Dave Noveck 10529 Network Appliance 10530 495 East Java Drive 10531 Sunnyvale, CA 94089 10533 Phone: +1 781-861-9291 10534 E-mail: dave.noveck@netapp.com 10536 Draft Specification NFS version 4 Protocol February 2000 10538 David Robinson 10539 Sun Microsystems, Inc. 10540 901 San Antonio Road 10541 Palo Alto, CA 94303 10543 Phone: +1 650-786-5088 10544 E-mail: david.robinson@eng.sun.com 10546 Robert Thurlow 10547 Sun Microsystems, Inc. 10548 901 San Antonio Road 10549 Palo Alto, CA 94303 10551 Phone: +1 650-786-5096 10552 E-mail: robert.thurlow@eng.sun.com 10554 Draft Specification NFS version 4 Protocol February 2000 10556 21. Full Copyright Statement 10558 "Copyright (C) The Internet Society (2000). All Rights Reserved. 10560 This document and translations of it may be copied and furnished to 10561 others, and derivative works that comment on or otherwise explain it 10562 or assist in its implementation may be prepared, copied, published 10563 and distributed, in whole or in part, without restriction of any 10564 kind, provided that the above copyright notice and this paragraph are 10565 included on all such copies and derivative works. However, this 10566 document itself may not be modified in any way, such as by removing 10567 the copyright notice or references to the Internet Society or other 10568 Internet organizations, except as needed for the purpose of 10569 developing Internet standards in which case the procedures for 10570 copyrights defined in the Internet Standards process must be 10571 followed, or as required to translate it into languages other than 10572 English. 10574 The limited permissions granted above are perpetual and will not be 10575 revoked by the Internet Society or its successors or assigns. 10577 This document and the information contained herein is provided on an 10578 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 10579 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 10580 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 10581 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 10582 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."