idnits 2.17.1 draft-ietf-nfsv4-05.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 152) being 61 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 249 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 604 has weird spacing: '...ned int uin...' == Line 608 has weird spacing: '...d hyper uint6...' == Line 673 has weird spacing: '...8string typ...' == Line 758 has weird spacing: '...8string ser...' == Line 824 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 8835 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 10211 looks like a reference -- Missing reference section? 'RFC1813' on line 10229 looks like a reference -- Missing reference section? 'RFC1831' on line 10235 looks like a reference -- Missing reference section? 'RFC1832' on line 10243 looks like a reference -- Missing reference section? 'RFC2623' on line 10305 looks like a reference -- Missing reference section? 'RFC1964' on line 911 looks like a reference -- Missing reference section? 'RFCXXXX' on line 10318 looks like a reference -- Missing reference section? 'RFC2078' on line 10273 looks like a reference -- Missing reference section? 'RFC2203' on line 10287 looks like a reference -- Missing reference section? 'RFC1700' on line 10223 looks like a reference -- Missing reference section? 'RFC1833' on line 10249 looks like a reference -- Missing reference section? 'RFC2581' on line 877 looks like a reference -- Missing reference section? 'RFC2025' on line 10255 looks like a reference -- Missing reference section? 'RFC2054' on line 10261 looks like a reference -- Missing reference section? 'RFC2055' on line 10267 looks like a reference -- Missing reference section? 'RFC2624' on line 10312 looks like a reference -- Missing reference section? 'XNFS' on line 10357 looks like a reference -- Missing reference section? '4' on line 2499 looks like a reference -- Missing reference section? 'Juszczak' on line 10169 looks like a reference -- Missing reference section? 'ISO10646' on line 10164 looks like a reference -- Missing reference section? 'RFC2277' on line 10293 looks like a reference -- Missing reference section? 'RFC1345' on line 10217 looks like a reference -- Missing reference section? 'RFC2279' on line 10299 looks like a reference -- Missing reference section? 'RFC2152' on line 10279 looks like a reference -- Missing reference section? 'Unicode1' on line 10344 looks like a reference -- Missing reference section? 'Unicode2' on line 10351 looks like a reference -- Missing reference section? 'Gray' on line 10159 looks like a reference -- Missing reference section? 'Kazar' on line 10178 looks like a reference -- Missing reference section? 'Macklem' on line 10185 looks like a reference -- Missing reference section? 'Mogul' on line 10342 looks like a reference -- Missing reference section? 'Nowicki' on line 10200 looks like a reference -- Missing reference section? 'Pawlowski' on line 10205 looks like a reference -- Missing reference section? 'Sandberg' on line 10324 looks like a reference -- Missing reference section? 'Srinivasan' on line 10335 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-05.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 9. Client-Side Caching . . . . . . . . . . . . . . . . . . . 73 159 9.1. Performance Challenges for Client-Side Caching . . . . . 73 160 9.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 74 161 9.2.1. Delegation Recovery . . . . . . . . . . . . . . . . . 76 162 9.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 77 163 9.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . . 78 164 9.3.2. Data Caching and File Locking . . . . . . . . . . . . 78 165 9.3.3. Data Caching and Mandatory File Locking . . . . . . . 80 167 Draft Specification NFS version 4 Protocol February 2000 169 9.3.4. Data Caching and File Identity . . . . . . . . . . . . 80 170 9.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 81 171 9.4.1. Open Delegation and Data Caching . . . . . . . . . . . 84 172 9.4.2. Open Delegation and File Locks . . . . . . . . . . . . 85 173 9.4.3. Recall of Open Delegation . . . . . . . . . . . . . . 85 174 9.4.4. Delegation Revocation . . . . . . . . . . . . . . . . 87 175 9.5. Data Caching and Revocation . . . . . . . . . . . . . . 87 176 9.5.1. Revocation Recovery for Write Open Delegation . . . . 88 177 9.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 89 178 9.7. Name Caching . . . . . . . . . . . . . . . . . . . . . . 90 179 9.8. Directory Caching . . . . . . . . . . . . . . . . . . . 91 180 10. Minor Versioning . . . . . . . . . . . . . . . . . . . . 93 181 11. Internationalization . . . . . . . . . . . . . . . . . . 96 182 11.1. Universal Versus Local Character Sets . . . . . . . . . 96 183 11.2. Overview of Universal Character Set Standards . . . . . 97 184 11.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 98 185 11.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 99 186 11.5. Normalization . . . . . . . . . . . . . . . . . . . . . 99 187 12. Error Definitions . . . . . . . . . . . . . . . . . . . . 101 188 13. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 106 189 13.1. Compound Procedure . . . . . . . . . . . . . . . . . . 106 190 13.2. Evaluation of a Compound Request . . . . . . . . . . . 107 191 13.3. Synchronous Modifying Operations . . . . . . . . . . . 107 192 13.4. Operation Values . . . . . . . . . . . . . . . . . . . 108 193 14. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 109 194 14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 109 195 14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 110 196 14.2.1. Operation 3: ACCESS - Check Access Rights . . . . . . 113 197 14.2.2. Operation 4: CLOSE - Close File . . . . . . . . . . . 117 198 14.2.3. Operation 5: COMMIT - Commit Cached Data . . . . . . 119 199 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 122 200 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 201 Recovery . . . . . . . . . . . . . . . . . . . . . . 125 202 14.2.6. Operation 8: DELEGRETURN - Return Delegation . . . . 126 203 14.2.7. Operation 9: GETATTR - Get Attributes . . . . . . . . 127 204 14.2.8. Operation 10: GETFH - Get Current Filehandle . . . . 129 205 14.2.9. Operation 11: LINK - Create Link to a File . . . . . 131 206 14.2.10. Operation 12: LOCK - Create Lock . . . . . . . . . . 133 207 14.2.11. Operation 13: LOCKT - Test For Lock . . . . . . . . 136 208 14.2.12. Operation 14: LOCKU - Unlock File . . . . . . . . . 138 209 14.2.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . 140 210 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory . . 143 211 14.2.15. Operation 17: NVERIFY - Verify Difference in 212 Attributes . . . . . . . . . . . . . . . . . . . . . 145 213 14.2.16. Operation 18: OPEN - Open a Regular File . . . . . . 147 214 14.2.17. Operation 19: OPENATTR - Open Named Attribute 215 Directory . . . . . . . . . . . . . . . . . . . . . 156 216 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . 158 218 Draft Specification NFS version 4 Protocol February 2000 220 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access161 221 14.2.20. Operation 22: PUTFH - Set Current Filehandle . . . . 163 222 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle . . . 164 223 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle . . . 165 224 14.2.23. Operation 25: READ - Read from File . . . . . . . . 166 225 14.2.24. Operation 26: READDIR - Read Directory . . . . . . . 169 226 14.2.25. Operation 27: READLINK - Read Symbolic Link . . . . 173 227 14.2.26. Operation 28: REMOVE - Remove Filesystem Object . . 175 228 14.2.27. Operation 29: RENAME - Rename Directory Entry . . . 177 229 14.2.28. Operation 30: RENEW - Renew a Lease . . . . . . . . 180 230 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle . 182 231 14.2.30. Operation 32: SAVEFH - Save Current Filehandle . . . 184 232 14.2.31. Operation 33: SECINFO - Obtain Available Security . 185 233 14.2.32. Operation 34: SETATTR - Set Attributes . . . . . . . 187 234 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid . . . 190 235 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 192 236 14.2.35. Operation 37: VERIFY - Verify Same Attributes . . . 194 237 14.2.36. Operation 38: WRITE - Write to File . . . . . . . . 196 238 15. NFS Version 4 Callback Procedures . . . . . . . . . . . . 201 239 15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 201 240 15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 202 241 15.2.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . 204 242 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation . 206 243 16. Security Considerations . . . . . . . . . . . . . . . . . 208 244 17. IANA Considerations . . . . . . . . . . . . . . . . . . . 209 245 17.1. Named Attribute Definition . . . . . . . . . . . . . . 209 246 18. RPC definition file . . . . . . . . . . . . . . . . . . . 210 247 19. Bibliography . . . . . . . . . . . . . . . . . . . . . . 242 248 20. Authors . . . . . . . . . . . . . . . . . . . . . . . . . 247 249 20.1. Editor's Address . . . . . . . . . . . . . . . . . . . 247 250 20.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 247 251 21. Full Copyright Statement . . . . . . . . . . . . . . . . 249 253 Draft Specification NFS version 4 Protocol February 2000 255 1. Introduction 257 The NFS version 4 protocol is a further revision of the NFS protocol 258 defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains 259 the essential characteristics of previous versions: design for easy 260 recovery, independent of transport protocols, operating systems and 261 filesystems, simplicity, and good performance. The NFS version 4 262 revision has the following goals: 264 o Improved access and good performance on the Internet. 266 The protocol is designed to transit firewalls easily, perform 267 well where latency is high and bandwidth is low, and scale to 268 very large numbers of clients per server. 270 o Strong security with negotiation built into the protocol. 272 The protocol builds on the work of the ONCRPC working group in 273 supporting the RPCSEC_GSS protocol. Additionally, the NFS 274 version 4 protocol provides a mechanism to allow clients and 275 servers the ability to negotiate security and require clients 276 and servers to support a minimal set of security schemes. 278 o Good cross-platform interoperability. 280 The protocol features a file system model that provides a 281 useful, common set of features that does not unduly favor one 282 file system or operating system over another. 284 o Designed for protocol extensions. 286 The protocol is designed to accept standard extensions that do 287 not compromise backward compatibility. 289 1.1. Overview of NFS Version 4 Features 291 To provide a reasonable context for the reader, the major features of 292 NFS version 4 protocol will be reviewed in brief. This will be done 293 to provide an appropriate context for both the reader who is familiar 294 with the previous versions of the NFS protocol and the reader that is 295 new to the NFS protocols. For the reader new to the NFS protocols, 296 there is still a fundamental knowledge that is expected. The reader 297 should be familiar with the XDR and RPC protocols as described in 299 Draft Specification NFS version 4 Protocol February 2000 301 [RFC1831] and [RFC1832]. A basic knowledge of file systems and 302 distributed file systems is expected as well. 304 1.1.1. RPC and Security 306 As with previous versions of NFS, the External Data Representation 307 (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS 308 version 4 protocol are those defined in [RFC1831] and [RFC1832]. To 309 meet end to end security requirements, the RPCSEC_GSS framework 310 [RFC2623] will be used to extend the basic RPC security. With the 311 use of RPCSEC_GSS, various mechanisms can be provided to offer 312 authentication, integrity, and privacy to the NFS version 4 protocol. 313 Kerberos V5 will be used as described in [RFC1964] to provide one 314 security framework. The LIPKEY GSS-API mechanism described in 315 [RFCXXXX] will be used to provide for the use of user password and 316 server public key by the NFS version 4 protocol. With the use of 317 RPCSEC_GSS, other mechanisms may also be specified and used for NFS 318 version 4 security. 320 To enable in-band security negotiation, the NFS version 4 protocol 321 has added a new operation which provides the client a method of 322 querying the server about its policies regarding which security 323 mechanisms must be used for access to the server's file system 324 resources. With this, the client can securely match the security 325 mechanism that meets the policies specified at both the client and 326 server. 328 1.1.2. Procedure and Operation Structure 330 A significant departure from the previous versions of the NFS 331 protocol is the introduction of the COMPOUND procedure. For the NFS 332 version 4 protocol, there are two RPC procedures, NULL and COMPOUND. 333 The COMPOUND procedure is defined in terms of operations and these 334 operations correspond more closely to the traditional NFS procedures. 335 With the use of the COMPOUND procedure, the client is able to build 336 simple or complex requests. These COMPOUND requests allow for a 337 reduction in the number of RPCs needed for logical file system 338 operations. For example, without previous contact with a server a 339 client will be able to read data from a file in one request by 340 combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. 341 With previous versions of the NFS protocol, this type of single 342 request was not possible. 344 The model used for COMPOUND is very simple. There is no logical OR 345 or ANDing of operations. The operations combined within a COMPOUND 346 request are evaluated in order by the server. Once an operation 348 Draft Specification NFS version 4 Protocol February 2000 350 returns a failing result, the evaluation ends and the results of all 351 evaluated operations are returned to the client. 353 The NFS version 4 protocol continues to have the client refer to a 354 file or directory at the server by a "filehandle". The COMPOUND 355 procedure has a method of passing a filehandle from one operation to 356 another within the sequence of operations. There is a concept of a 357 "current filehandle" and "saved filehandle". Most operations use the 358 "current filehandle" as the file system object to operate upon. The 359 "saved filehandle" is used as temporary filehandle storage within a 360 COMPOUND procedure as well as an additional operand for certain 361 operations. 363 1.1.3. File System Model 365 The general file system model used for the NFS version 4 protocol is 366 the same as previous versions. The server file system is 367 hierarchical with the regular files contained within being treated as 368 opaque byte streams. In a slight departure, file and directory names 369 are encoded with UTF-8 to deal with the basics of 370 internationalization. 372 The NFS version 4 protocol does not require a separate protocol to 373 provide for the initial mapping between path name and filehandle. 374 Instead of using the older MOUNT protocol for this mapping, the 375 server provides a ROOT filehandle that represents the logical root or 376 top of the file system tree provided by the server. The server 377 provides multiple file systems by glueing them together with pseudo 378 file systems. These pseudo file systems provide for potential gaps 379 in the path names between real file systems. 381 1.1.3.1. Filehandle Types 383 In previous versions of the NFS protocol, the filehandle provided by 384 the server was guaranteed to be valid or persistent for the lifetime 385 of the file system object to which it referred. For some server 386 implementations, this persistence requirement has been difficult to 387 meet. For the NFS version 4 protocol, this requirement has been 388 relaxed by introducing another type of filehandle, volatile. With 389 persistent and volatile filehandle types, the server implementation 390 can match the abilities of the file system at the server along with 391 the operating environment. The client will have knowledge of the 392 type of filehandle being provided by the server and can be prepared 393 to deal with the semantics of each. 395 Draft Specification NFS version 4 Protocol February 2000 397 1.1.3.2. Attribute Types 399 The NFS version 4 protocol introduces three classes of file system or 400 file attributes. Like the additional filehandle type, the 401 classification of file attributes has been done to ease server 402 implementations along with extending the overall functionality of the 403 NFS protocol. This attribute model is structured to be extensible 404 such that new attributes can be introduced in minor revisions of the 405 protocol without requiring significant rework. 407 The three classifications are: mandatory, recommended and named 408 attributes. This is a significant departure from the previous 409 attribute model used in the NFS protocol. Previously, the attributes 410 for the file system and file objects were a fixed set of mainly Unix 411 attributes. If the server or client did not support a particular 412 attribute, it would have to simulate the attribute the best it could. 414 Mandatory attributes are the minimal set of file or file system 415 attributes that must be provided by the server and must be properly 416 represented by the server. Recommended attributes represent 417 different file system types and operating environments. The 418 recommended attributes will allow for better interoperability and the 419 inclusion of more operating environments. The mandatory and 420 recommended attribute sets are traditional file or file system 421 attributes. The third type of attribute is the named attribute. A 422 named attribute is an opaque byte stream that is associated with a 423 directory or file and referred to by a string name. Named attributes 424 are meant to be used by client applications as a method to associate 425 application specific data with a regular file or directory. 427 One significant addition to the recommended set of file attributes is 428 the Access Control List (ACL) attribute. This attribute provides for 429 directory and file access control beyond the model used in previous 430 versions of the NFS protocol. The ACL definition allows for 431 specification of user and group level access control. 433 1.1.3.3. File System Replication and Migration 435 With the use of a special file attribute, the ability to migrate or 436 replicate server file systems is enabled within the protocol. The 437 file system locations attribute provides a method for the client to 438 probe the server about the location of a file system. In the event 439 of a migration of a file system, the client will receive an error 440 when operating on the file system and it can then query as to the new 441 file system location. Similar steps are used for replication, the 442 client is able to query the server for the multiple available 443 locations of a particular file system. From this information, the 445 Draft Specification NFS version 4 Protocol February 2000 447 client can use its own policies to access the appropriate file system 448 location. 450 1.1.4. OPEN and CLOSE 452 The NFS version 4 protocol introduces OPEN and CLOSE operations. The 453 OPEN operation provides a single point where file lookup, creation, 454 and share semantics can be combined. The CLOSE operation also 455 provides for the release of state accumulated by OPEN. 457 1.1.5. File locking 459 With the NFS version 4 protocol, the support for byte range file 460 locking is part of the NFS protocol. The file locking support is 461 structured so that an RPC callback mechanism is not required. This 462 is a departure from the previous versions of the NFS file locking 463 protocol, Network Lock Manager (NLM). The state associated with file 464 locks is maintained at the server under a lease-based model. The 465 server defines a single lease period for all state held by a NFS 466 client. If the client does not renew its lease within the defined 467 period, all state associated with the client's lease may be released 468 by the server. The client may renew its lease with use of the RENEW 469 operation or implicitly by use of other operations (primarily READ). 471 1.1.6. Client Caching and Delegation 473 The file, attribute, and directory caching for the NFS version 4 474 protocol is similar to previous versions. Attributes and directory 475 information are cached for a duration determined by the client. At 476 the end of a predefined timeout, the client will query the server to 477 see if the related file system object has been updated. 479 For file data, the client checks its cache validity when the file is 480 opened. A query is sent to the server to determine if the file has 481 been changed. Based on this information, the client determines if 482 the data cache for the file should kept or released. Also, when the 483 file is closed, any modified data is written to the server. 485 If an application wants to serialize access to file data, file 486 locking of the file data ranges in question should be used. 488 The major addition to NFS version 4 in the area of caching is the 489 ability of the server to delegate certain responsibilities to the 490 client. When the server grants a delegation for a file to a client, 491 the client is guaranteed certain semantics with respect to the 493 Draft Specification NFS version 4 Protocol February 2000 495 sharing of that file with other clients. At OPEN, the server may 496 provid the client either a read or write delegation for the file. If 497 the client is granted a read delegation, it is assured that no other 498 client has the ability to write to the file for the duration of the 499 delegation. If the client is granted a write delegation, the client 500 is assured that no other client has read or write access to the file. 502 Delegations can be recalled by the server. If another client 503 requests access to the file in such a way that the access conflicts 504 with the granted delegation, the server is able to notify the initial 505 client and recall the delegation. This requires that a callback path 506 exist between the server and client. If this callback path does not 507 exist, then delegations can not be granted. The essence of a 508 delegation is that it allows the client to locally service operations 509 such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate 510 interaction with the server. 512 1.2. General Definitions 514 The following definitions are provided for the purpose of providing 515 an appropriate context for the reader. 517 Client The "client" is the entity that accesses the NFS server's 518 resources. The client may be an application which contains 519 the logic to access the NFS server directly. The client 520 may also be the traditional operating system client remote 521 file system services for a set of applications. 523 In the case of file locking the client is the entity that 524 maintains a set of locks on behalf of one or more 525 applications. This client is responsible for crash or 526 failure recovery for those locks it manages. 528 Note that multiple clients may share the same transport and 529 multiple clients may exist on the same network node. 531 Clientid A 64-bit quantity used as a unique, short-hand reference to 532 a client supplied Verifier and ID. The server is 533 responsible for supplying the Clientid. 535 Lease An interval of time defined by the server for which the 536 client is irrevokeably granted a lock. At the end of a 537 lease period the lock may be revoked if the lease has not 538 been extended. The lock must be revoked if a conflicting 539 lock has been granted after the lease interval. 541 Draft Specification NFS version 4 Protocol February 2000 543 All leases granted by a server have the same fixed 544 interval. 546 Lock The term "lock" is used to refer to both record (byte- 547 range) locks as well as file (share) locks unless 548 specifically stated otherwise. 550 Server The "Server" is the entity responsible for coordinating 551 client access to a set of file systems. 553 Stable Storage 554 NFS version 4 servers must be able to recover without data 555 loss from multiple power failures (including cascading 556 power failures, that is, several power failures in quick 557 succession), operating system failures, and hardware 558 failure of components other than the storage medium itself 559 (for example, disk, nonvolatile RAM). 561 Some examples of stable storage that are allowable for an 562 NFS server include: 564 1. Media commit of data, that is, the modified data has 565 been successfully written to the disk media, 566 for example, the disk platter. 568 2. An immediate reply disk drive with battery-backed 569 on-drive intermediate storage or uninterruptible power 570 system (UPS). 572 3. Server commit of data with battery-backed intermediate 573 storage and recovery software. 575 4. Cache commit with uninterruptible power system (UPS) 576 and recovery software. 578 Stateid A 64-bit quantity returned by a server that uniquely 579 defines the locking state granted by the server for a 580 specific lock owner for a specific file. 582 A stateid composed of all bits 0 or all bits 1 has special 583 meaning and are reserved values. 585 Verifier A 64-bit quantity generated by the client that the server 586 can use to determine if the client has restarted and lost 587 all previous lock state. 589 Draft Specification NFS version 4 Protocol February 2000 591 2. Protocol Data Types 593 The syntax and semantics to describe the data types of the NFS 594 version 4 protocol are defined in the XDR [RFC1832] and RPC [RFC1831] 595 documents. The next sections build upon the XDR data types to define 596 types and structures specific to this protocol. 598 2.1. Basic Data Types 600 Data Type Definition 601 _____________________________________________________________________ 602 int32_t typedef int int32_t; 604 uint32_t typedef unsigned int uint32_t; 606 int64_t typedef hyper int64_t; 608 uint64_t typedef unsigned hyper uint64_t; 610 attrlist4 typedef opaque attrlist4<>; 611 Used for file/directory attributes 613 bitmap4 typedef uint32_t bitmap4<>; 614 Used in attribute array encoding. 616 changeid4 typedef uint64_t changeid4; 617 Used in definition of change_info 619 clientid4 typedef uint64_t clientid4; 620 Shorthand reference to client identification 622 component4 typedef utf8string component4; 623 Represents path name components 625 count4 typedef uint32_t count4; 626 Various count parameters (READ, WRITE, COMMIT) 628 length4 typedef uint64_t length4; 629 Describes LOCK lengths 631 linktext4 typedef utf8string linktext4; 632 Symbolic link contents 634 mode4 typedef uint32_t mode4; 635 Mode attribute data type 637 nfs_cookie4 typedef uint64_t nfs_cookie4; 638 Opaque cookie value for READDIR 640 Draft Specification NFS version 4 Protocol February 2000 642 nfs_fh4 typedef opaque nfs_fh4; 643 Filehandle definition; NFS4_FHSIZE is defined as 128 645 nfs_ftype4 enum nfs_ftype4; 646 Various defined file types 648 nfsstat4 enum nfsstat4; 649 Return value for operations 651 offset4 typedef uint64_t offset4; 652 Various offset designations (READ, WRITE, LOCK, COMMIT) 654 pathname4 typedef component4 pathname4<>; 655 Represents path name for LOOKUP, OPEN and others 657 qop4 typedef uint32_t qop4; 658 Quality of protection designation in SECINFO 660 sec_oid4 typedef opaque sec_oid4<>; 661 Security Object Identifier 662 The sec_oid4 data type is not really opaque. 663 Instead contains an ASN.1 OBJECT IDENTIFIER as used 664 by GSS-API in the mech_type argument to 665 GSS_Init_sec_context. See [RFC2078] for details. 667 seqid4 typedef uint32_t seqid4; 668 Sequence identifier used for file locking 670 stateid4 typedef uint64_t stateid4; 671 State identifier used for file locking and delegation 673 utf8string typedef opaque utf8string<>; 674 UTF-8 encoding for strings 676 verifier4 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 677 Verifier used for various operations (COMMIT, CREATE, 678 OPEN, READDIR, SETCLIENTID, WRITE) 679 NFS4_VERIFIER_SIZE is defined as 8 681 2.2. Structured Data Types 683 nfstime4 684 struct nfstime4 { 685 int64_t seconds; 686 uint32_t nseconds; 688 Draft Specification NFS version 4 Protocol February 2000 690 } 692 The nfstime4 structure gives the number of seconds and 693 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 694 Universal Time (UTC). Values greater than zero for the seconds 695 field denote dates after the 0 hour January 1, 1970. Values 696 less than zero for the seconds field denote dates before the 0 697 hour January 1, 1970. In both cases, the nseconds field is to 698 be added to the seconds field for the final time representation. 699 For example, if the time to be represented is one-half second 700 before 0 hour January 1, 1970, the seconds field would have a 701 value of negative one (-1) and the nseconds fields would have a 702 value of one-half second (500000000). Values greater than 703 999,999,999 for nseconds are considered invalid. 705 This data type is used to pass time and date information. A 706 server converts to and from local time when processing time 707 values, preserving as much accuracy as possible. If the 708 precision of timestamps stored for a file system object is less 709 than defined, loss of precision can occur. An adjunct time 710 maintenance protocol is recommended to reduce client and server 711 time skew. 713 time_how4 715 enum time_how4 { 716 SET_TO_SERVER_TIME4 = 0, 717 SET_TO_CLIENT_TIME4 = 1 718 }; 720 settime4 722 union settime4 switch (time_how4 set_it) { 723 case SET_TO_CLIENT_TIME4: 724 nfstime4 time; 725 default: 726 void; 727 }; 729 The above definitions are used as the attribute definitions to 730 set time values. If set_it is SET_TO_SERVER_TIME4, then the 731 server uses its local time for the time value. 733 specdata4 735 Draft Specification NFS version 4 Protocol February 2000 737 struct specdata4 { 738 uint32_t specdata1; 739 uint32_t specdata2; 740 }; 742 This data type represents additional information for the device 743 file types NF4CHR and NF4BLK. 745 fsid4 747 struct fsid4 { 748 uint64_t major; 749 uint64_t minor; 750 }; 752 This type is the file system identifier that is used as a 753 mandatory attribute. 755 fs_location4 757 struct fs_location4 { 758 utf8string server<>; 759 pathname4 rootpath; 760 }; 762 fs_locations4 764 struct fs_locations4 { 765 pathname4 fs_root; 766 fs_location4 locations<>; 767 }; 769 The fs_location4 and fs_locations4 data types are used for the 770 fs_locations recommended attribute which is used for migration 771 and replication support. 773 fattr4 775 struct fattr4 { 776 bitmap4 attrmask; 777 attrlist4 attr_vals; 778 }; 780 The fattr4 structure is used to represent file and directory 782 Draft Specification NFS version 4 Protocol February 2000 784 attributes. 786 The bitmap is a counted array of 32 bit integers used to contain 787 bit values. The position of the integer in the array that 788 contains bit n can be computed from the expression (n / 32) and 789 its bit within that integer is (n mod 32). 791 0 1 792 +-----------+-----------+-----------+-- 793 | count | 31 .. 0 | 63 .. 32 | 794 +-----------+-----------+-----------+-- 796 change_info4 798 struct change_info4 { 799 bool atomic; 800 changeid4 before; 801 changeid4 after; 802 }; 804 This structure is used with the CREATE, LINK, REMOVE, RENAME 805 operations to let the client know value of the change attribute 806 for the directory in which the target file system object 807 resides. 809 clientaddr4 811 struct clientaddr4 { 812 /* see struct rpcb in RFC 1833 */ 813 string r_netid<>; /* network id */ 814 string r_addr<>; /* universal address */ 815 }; 817 The clientaddr4 structure is used as part of the SETCLIENT 818 operation to specify the address of either the client that is 819 using a clientid or as part of the call back registration. 821 cb_client4 823 struct cb_client4 { 824 unsigned int cb_program; 825 clientaddr4 cb_location; 826 }; 828 This structure is used by the client to inform the server of its 830 Draft Specification NFS version 4 Protocol February 2000 832 call back address; includes the program number and client 833 address. 835 nfs_client_id4 837 struct nfs_client_id4 { 838 verifier4 verifier; 839 opaque id<>; 840 }; 842 This structure is part of the arguments to the SETCLIENTID 843 operation. 845 nfs_lockowner4 847 struct nfs_lockowner4 { 848 clientid4 clientid; 849 opaque owner<>; 850 }; 852 This structure is used to identify the owner of a OPEN share or 853 file lock. 855 Draft Specification NFS version 4 Protocol February 2000 857 3. RPC and Security Flavor 859 The NFS version 4 protocol is a Remote Procedure Call (RPC) 860 application that uses RPC version 2 and the corresponding eXternal 861 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 862 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 863 the mechanism to deliver stronger security for the NFS version 4 864 protocol. 866 3.1. Ports and Transports 868 Historically, NFS version 2 and version 3 servers have resided on 869 port 2049. The registered port 2049 [RFC1700] for the NFS protocol 870 should be the default configuration. Using the registered port for 871 NFS services means the NFS client will not need to use the RPC 872 binding protocols as described in [RFC1833]; this will allow NFS to 873 transit firewalls. 875 The transport used by the RPC service for the NFS version 4 protocol 876 MUST provide congestion control comparable to that defined for TCP in 877 [RFC2581]. If the operating environment implements TCP, the NFS 878 version 4 protocol SHOULD be supported over TCP. The NFS client and 879 server may use other transports if they support congestion control as 880 defined above and in those cases a mechanism may be provided to 881 override TCP usage in favor of another transport. 883 If TCP is used as the transport, the client and server SHOULD use 884 persistent connections. This will prevent the weakening of TCP's 885 congestion control via short lived connections. 887 3.2. Security Flavors 889 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 890 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 891 additional security flavor of RPCSEC_GSS has been introduced which 892 uses the functionality of GSS-API [RFC2078]. This allows for the use 893 of varying security mechanisms by the RPC layer without the 894 additional implementation overhead of adding RPC security flavors. 895 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 896 enable the mandatory security mechanism. Other flavors, such as, 897 AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well. 899 3.2.1. Security mechanisms for NFS version 4 901 The use of RPCSEC_GSS requires selection of: mechanism, quality of 902 protection, and service (authentication, integrity, privacy). The 903 remainder of this document will refer to these three parameters of 905 Draft Specification NFS version 4 Protocol February 2000 907 the RPCSEC_GSS security as the security triple. 909 3.2.1.1. Kerberos V5 as security triple 911 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 912 implemented and provide the following security triples. 914 column descriptions: 916 1 == number of pseudo flavor 917 2 == name of pseudo flavor 918 3 == mechanism's OID 919 4 == mechanism's algorithm(s) 920 5 == RPCSEC_GSS service 922 1 2 3 4 5 923 ----------------------------------------------------------------------- 924 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 925 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 926 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 927 for integrity, 928 and 56 bit DES 929 for privacy. 931 Note that the pseudo flavor is presented here as a mapping aid to the 932 implementor. Because this NFS protocol includes a method to 933 negotiate security and it understands the GSS-API mechanism, the 934 pseudo flavor is not needed. The pseudo flavor is needed for NFS 935 version 3 since the security negotiation is done via the MOUNT 936 protocol. 938 For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please 939 see [RFC2623]. 941 3.2.1.2. LIPKEY as a security triple 943 The LIPKEY GSS-API mechanism as described in [RFCXXXX] MUST be 944 implemented and provide the following security triples. The 945 definition of the columns matches the previous subsection "Kerberos 946 V5 as security triple" 948 1 2 3 4 5 949 ----------------------------------------------------------------------- 950 390006 lipkey TBD negotiated rpc_gss_svc_none 951 390007 lipkey-i TBD negotiated rpc_gss_svc_integrity 952 390008 lipkey-p TBD negotiated rpc_gss_svc_privacy 954 Draft Specification NFS version 4 Protocol February 2000 956 The mechanism algorithm is listed as "negotiated". This is because 957 LIPKEY is layered on SPKM-3 and in SPKM-3 [RFCXXXX] the 958 confidentiality and integrity algorithms are negotiated. Since 959 SPKM-3 specifies HMAC-MD5 for integrity as MANDATORY, 128 bit 960 cast5CBC for confidentiality for privacy as MANDATORY, and further 961 specifies that HMAC-MD5 and cast5CBC MUST be listed first before 962 weaker algorithms, specifying "negotiated" in column 4 does not 963 impair interoperability. In the event an SPKM-3 peer does not 964 support the mandatory algorithms, the other peer is free to accept or 965 reject the GSS-API context creation. 967 Because SPKM-3 negotiates the algorithms, subsequent calls to 968 LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality 969 of protection value of 0 (zero). See section 5.2 of [RFC2025] for an 970 explanation. 972 LIPKEY uses SPKM-3 to create a secure channel in which to pass a user 973 name and password from the client to the user. Once the user name 974 and password have been accepted by the server, calls to the LIPKEY 975 context are redirected to the SPKM-3 context. See [RFCXXXX] for more 976 details. 978 3.2.1.3. SPKM-3 as a security triple 980 The SPKM-3 GSS-API mechanism as described in [RFCXXXX] MUST be 981 implemented and provide the following security triples. The 982 definition of the columns matches the previous subsection "Kerberos 983 V5 as security triple". 985 1 2 3 4 5 986 ----------------------------------------------------------------------- 987 390009 spkm3 TBD negotiated rpc_gss_svc_none 988 390010 spkm3i TBD negotiated rpc_gss_svc_integrity 989 390011 spkm3p TBD negotiated rpc_gss_svc_privacy 991 For a discussion as to why the mechanism algorithm is listed as 992 "negotiated", see the previous section "LIPKEY as a security triple." 994 Because SPKM-3 negotiates the algorithms, subsequent calls to SPKM- 995 3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality of 996 protection value of 0 (zero). See section 5.2 of [RFC2025] for an 997 explanation. 999 Even though LIPKEY is layered onto SPKM-3, SPKM-3 is specified as a 1000 mandatory set of triples to handle the situation when the initiator 1001 (the client) is anonymous. If the initiator is anonymous, there will 1002 not be a user name and password to send to the target (the server). 1004 Draft Specification NFS version 4 Protocol February 2000 1006 3.3. Security Negotiation 1008 With the NFS version 4 server potentially offering multiple security 1009 mechanisms, the client needs a method to determine or negotiate which 1010 mechanism is to be used for its communication with the server. The 1011 NFS server may have multiple points within its file system name space 1012 that are available for use by NFS clients. In turn the NFS server 1013 may be configured such that each of these entry points may have 1014 different or multiple security mechanisms in use. 1016 The security negotiation between client and server must be done with 1017 a secure channel to eliminate the possibility of a third party 1018 intercepting the negotiation sequence and forcing the client and 1019 server to choose a lower level of security than required or desired. 1021 3.3.1. Security Error 1023 Based on the assumption that each NFS version 4 client and server 1024 must support a minimum set of security (i.e. LIPKEY, SPKM-3, and 1025 Kerberos-V5 all under RPCSEC_GSS), the NFS client will start its 1026 communication with the server with one of the minimal security 1027 triples. During communication with the server, the client may 1028 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 1029 server to notify the client that the security triple currently being 1030 used is not appropriate for access to the server's file system 1031 resources. The client is then responsible for determining what 1032 security triples are available at the server and choose one which is 1033 appropriate for the client. 1035 3.3.2. SECINFO 1037 The new SECINFO operation will allow the client to determine, on a 1038 per filehandle basis, what security triple is to be used for server 1039 access. In general, the client will not have to use the SECINFO 1040 procedure except during initial communication with the server or when 1041 the client crosses policy boundaries at the server. It is possible 1042 that the server's policies change during the client's interaction 1043 therefore forcing the client to negotiate a new security triple. 1045 3.4. Callback RPC Authentication 1047 The callback RPC (described later) must mutually authenticate the NFS 1048 server to the principal that acquired the delegation (also described 1049 later), using the same security flavor the original delegation 1050 operation used. 1052 Draft Specification NFS version 4 Protocol February 2000 1054 For AUTH_NONE, there are no principals, so this is a non-issue. 1056 For AUTH_SYS, the server simply uses the AUTH_SYS credential that the 1057 user used when it set up the delegation. 1059 For AUTH_DH, one commonly used convention is that the server uses the 1060 credentional corresponding to this AUTH_DH principal: 1062 unix.host@domain 1064 where host and domain are variables corresponding to the name of 1065 server host and directory services domain in which it lives such as a 1066 Network Information System domain or a DNS domain. 1068 Regardless of what security mechanism under RPCSEC_GSS is being used, 1069 the NFS server, MUST identify itself in GSS-API via a 1070 GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE 1071 names are of the form: 1073 service@hostname 1075 For NFS, the "service" element is 1077 nfs 1079 Implementations of security mechanisms will convert nfs@hostname to 1080 various different forms. For Kerberos V5 and LIPKEY, the following 1081 form is RECOMMENDED: 1083 nfs/hostname 1085 For Kerberos V5, nfs/hostname would be a server principal in the 1086 Kerberos Key Distribution Center database. For LIPKEY, this would be 1087 the username passed to the target (the NFS version 4 client that 1088 receives the callback). 1090 It should be noted that LIPKEY may not work for callbacks, since the 1091 LIPKEY client uses a user id/password. If the NFS client receiving 1092 the callback can authenticate the NFS server's user name/password 1093 pair, and if the user that the NFS server is authenticating to has a 1094 public key certificiate, then it works. 1096 Draft Specification NFS version 4 Protocol February 2000 1098 4. Filehandles 1100 The filehandle in the NFS protocol is a per server unique identifier 1101 for a file system object. The contents of the filehandle are opaque 1102 to the client. Therefore, the server is responsible for translating 1103 the filehandle to an internal representation of the file system 1104 object. Since the filehandle is the client's reference to an object 1105 and the client may cache this reference, the server should not reuse 1106 a filehandle for another file system object. If the server needs to 1107 reuse a filehandle value, the time elapsed before reuse SHOULD be 1108 large enough that it is likely the client no longer has a cached copy 1109 of the reused filehandle value. 1111 4.1. Obtaining the First Filehandle 1113 The operations of the NFS protocol are defined in terms of one or 1114 more filehandles. Therefore, the client needs a filehandle to 1115 initiate communication with the server. With the NFS version 2 1116 protocol [RFC1094] and the NFS version 3 protocol [RFC1813], there 1117 exists an ancillary protocol to obtain this first filehandle. The 1118 MOUNT protocol, RPC program number 100005, provides the mechanism of 1119 translating a string based file system path name to a filehandle 1120 which can then be used by the NFS protocols. 1122 The MOUNT protocol has deficiencies in the area of security and use 1123 via firewalls. This is one reason that the use of the public 1124 filehandle was introduced in [RFC2054] and [RFC2055]. With the use 1125 of the public filehandle in combination with the LOOKUP procedure in 1126 the NFS version 2 and 3 protocols, it has been demonstrated that the 1127 MOUNT protocol is unnecessary for viable interaction between NFS 1128 client and server. 1130 Therefore, the NFS version 4 protocol will not use an ancillary 1131 protocol for translation from string based path names to a 1132 filehandle. Two special filehandles will be used as starting points 1133 for the NFS client. 1135 4.1.1. Root Filehandle 1137 The first of the special filehandles is the ROOT filehandle. The 1138 ROOT filehandle is the "conceptual" root of the file system name 1139 space at the NFS server. The client uses or starts with the ROOT 1140 filehandle by employing the PUTROOTFH operation. The PUTROOTFH 1141 operation instructs the server to set the "current" filehandle to the 1142 ROOT of the server's file tree. Once this PUTROOTFH operation is 1143 used, the client can then traverse the entirety of the server's file 1145 Draft Specification NFS version 4 Protocol February 2000 1147 tree with the LOOKUP procedure. A complete discussion of the server 1148 name space is in the section "NFS Server Name Space". 1150 4.1.2. Public Filehandle 1152 The second special filehandle is the PUBLIC filehandle. Unlike the 1153 ROOT filehandle, the PUBLIC filehandle may be bound or represent an 1154 arbitrary file system object at the server. The server is 1155 responsible for this binding. It may be that the PUBLIC filehandle 1156 and the ROOT filehandle refer to the same file system object. 1157 However, it is up to the administrative software at the server and 1158 the policies of the server administrator to define the binding of the 1159 PUBLIC filehandle and server file system object. The client may not 1160 make any assumptions about this binding. 1162 4.2. Filehandle Types 1164 In the NFS version 2 and 3 protocols, there was one type of 1165 filehandle with a single set of semantics. The NFS version 4 1166 protocol introduces a new type of filehandle in an attempt to 1167 accommodate certain server environments. The first type of 1168 filehandle is 'persistent'. The semantics of a persistent filehandle 1169 are the same as the filehandles of the NFS version 2 and 3 protocols. 1170 The second or new type of filehandle is the "volatile" filehandle. 1172 The volatile filehandle type is being introduced to address server 1173 functionality or implementation issues which make correct 1174 implementation of a persistent filehandle infeasible. Some server 1175 environments do not provide a file system level invariant that can be 1176 used to construct a persistent filehandle. The underlying server 1177 file system may not provide the invariant or the server's file system 1178 programming interfaces may not provide access to the needed 1179 invariant. Volatile filehandles may ease the implementation of 1180 server functionality such as hierarchical storage management or file 1181 system reorganization or migration. However, the volatile filehandle 1182 increases the implementation burden for the client. However this 1183 increased burden is deemed acceptable based on the overall gains 1184 achieved by the protocol. 1186 Since the client will need to handle persistent and volatile 1187 filehandle differently, a file attribute is defined which may be used 1188 by the client to determine the filehandle types being returned by the 1189 server. 1191 Draft Specification NFS version 4 Protocol February 2000 1193 4.2.1. General Properties of a Filehandle 1195 The filehandle contains all the information the server needs to 1196 distinguish an individual file. To the client, the filehandle is 1197 opaque. The client stores filehandles for use in a later request and 1198 can compare two filehandles from the same server for equality by 1199 doing a byte-by-byte comparison. However, the client MUST NOT 1200 otherwise interpret the contents of filehandles. If two filehandles 1201 from the same server are equal, they MUST refer to the same file. If 1202 they are not equal, the client may use information provided by the 1203 server, in the form of file attributes, to determine whether they 1204 denote the same files or different files. The client would do this 1205 as necessary for client side caching. Servers SHOULD try to maintain 1206 a one-to-one correspondence between filehandles and files but this is 1207 not required. Clients MUST use filehandle comparisons only to 1208 improve performance, not for correct behavior. All clients need to 1209 be prepared for situations in which it cannot be determined whether 1210 two filehandles denote the same object and in such cases, avoid 1211 making invalid assumpions which might cause incorrect behavior. 1212 Further discussion of filehandle and attribute comparison in the 1213 context of data caching is presented in the section "Data Caching and 1214 File Identity". 1216 As an example, in the case that two different path names when 1217 traversed at the server terminate at the same file system object, the 1218 server SHOULD return the same filehandle for each path. This can 1219 occur if a hard link is used to create two file names which refer to 1220 the same underlying file object and associated data. For example, if 1221 paths /a/b/c and /a/d/c refer to the same file, the server SHOULD 1222 return the same filehandle for both path names traversals. 1224 4.2.2. Persistent Filehandle 1226 A persistent filehandle is defined as having a fixed value for the 1227 lifetime of the file system object to which it refers. Once the 1228 server creates the filehandle for a file system object, the server 1229 MUST accept the same filehandle for the object for the lifetime of 1230 the object. If the server restarts or reboots the NFS server must 1231 honor the same filehandle value as it did in the server's previous 1232 instantiation. Similarly, if the file system is migrated, the new 1233 NFS server must honor the same file handle as the old NFS server. 1235 The persistent filehandle will be become stale or invalid when the 1236 file system object is removed. When the server is presented with a 1237 persistent filehandle that refers to a deleted object, it MUST return 1238 an error of NFS4ERR_STALE. A filehandle may become stale when the 1239 file system containing the object is no longer available. The file 1241 Draft Specification NFS version 4 Protocol February 2000 1243 system may become unavailable if it exists on removable media and the 1244 media is no longer available at the server or the file system in 1245 whole has been destroyed or the file system has simply been removed 1246 from the server's name space (i.e. unmounted in a Unix environment). 1248 4.2.3. Volatile Filehandle 1250 A volatile filehandle does not share the same longevity 1251 characteristics of a persistent filehandle. The server may determine 1252 that a volatile filehandle is no longer valid at many different 1253 points in time. If the server can definitively determine that a 1254 volatile filehandle refers to an object that has been removed, the 1255 server should return NFS4ERR_STALE to the client (as is the case for 1256 persistent filehandles). In all other cases where the server 1257 determines that a volatile filehandle can no longer be used, it 1258 should return an error of NFS4ERR_FHEXPIRED. 1260 The mandatory attribute "fh_expire_type" is used by the client to 1261 determine what type of filehandle the server is providing for a 1262 particular file system. This attribute is a bitmask with the 1263 following values: 1265 FH4_PERSISTENT 1266 The value of FH4_PERSISTENT is used to indicate a persistent 1267 filehandle, which is valid until the object is removed from the 1268 file system. The server will not return NFS4ERR_FHEXPIRED for 1269 this filehandle. FH4_PERSISTENT is defined as a value in which 1270 none of the bits specified below are set. 1272 FH4_NOEXPIRE_WITH_OPEN 1273 The filehandle will not expire while client has the file open. 1274 If this bit is set, then the values FH4_VOLATILE_ANY or 1275 FH4_VOL_RENAME do not impact expiration while the file is open. 1276 Once the file is closed or if the FH4_NOEXPIRE_WITH_OPEN bit is 1277 false, the rest of the volatile related bits apply. 1279 FH4_VOLATILE_ANY 1280 The filehandle may expire at any time and will expire on during 1281 system migration. 1283 FH4_VOL_MIGRATION 1284 The filehandle will expire during file system migration and only 1285 then. May only be set if FH4_VOLATILE_ANY is not set. 1287 FH4_VOL_RENAME 1288 The filehandle may expire due to a rename. This includes a 1290 Draft Specification NFS version 4 Protocol February 2000 1292 rename by the requesting client or a rename by another client. 1293 May only be set if FH4_VOLATILE_ANY is not set. 1295 Servers which provide volatile filehandles should deny a RENAME or 1296 REMOVE that would effect an OPEN file or any of the components 1297 leading to the OPEN file. In addition, the server should deny all 1298 RENAME or REMOVE requests during the grace or lease period upon 1299 server restart. 1301 The reader may be wondering why there are three FH4_VOL* bits and why 1302 FH4_VOLATILE_ANY is exclusive of FH4_VOL_MIGRATION and 1303 FH4_VOL_RENAME. If the a filehandle is normally persistent but 1304 cannot persist across a file set migration, then the presence of the 1305 FH4_VOL_MIGRATION or FH4_VOL_RENAME tells the client that it can 1306 treat the file handle as persistent for purposes of maintaining a 1307 file name to file handle cache, except for the specific event 1308 described by the bit. However, FH4_VOLATILE_ANY tells the client 1309 that it should not maintain such a cache for unopened files. A 1310 server MUST not present FH4_VOLATILE_ANY with FH4_VOL_MIGRATION or 1311 FH4_VOL_RENAME as this will lead to confusion. FH4_VOLATILE_ANY 1312 implies that the file handle will expire upon migration or rename, in 1313 addition to other events. 1315 4.2.4. One Method of Constructing a Volatile Filehandle 1317 As mentioned, in some instances a filehandle is stale (no longer 1318 valid; perhaps because the file was removed from the server) or it is 1319 expired (the underlying file is valid but since the filehandle is 1320 volatile, it may have expired). Thus the server needs to be able to 1321 return NFS4ERR_STALE in the former case and NFS4ERR_FHEXPIRED in the 1322 latter case. This can be done by careful construction of the volatile 1323 filehandle. One possible implementation follows. 1325 A volatile filehandle, while opaque to the client could contain: 1327 [volatile bit = 1 | server boot time | slot | generation number] 1329 o slot is an index in the server volatile filehandle table 1331 o generation number is the generation number for the table 1332 entry/slot 1334 If the server boot time is less than the current server boot time, 1335 return NFS4ERR_FHEXPIRED. If slot is out of range, return 1336 NFS4ERR_BADHANDLE. If the generation number does not match, return 1338 Draft Specification NFS version 4 Protocol February 2000 1340 NFS4ERR_FHEXPIRED. 1342 When the server reboots, the table is gone (it is volatile). 1344 If volatile bit is 0, then it is a persistent filehandle with a 1345 different structure following it. 1347 4.3. Client Recovery from Filehandle Expiration 1349 If possible, the client SHOULD recover from the receipt of an 1350 NFS4ERR_FHEXPIRED error. The client must take on additional 1351 responsibility so that it may prepare itself to recover from the 1352 expiration of a volatile filehandle. If the server returns 1353 persistent filehandles, the client does not need these additional 1354 steps. 1356 For volatile filehandles, most commonly the client will need to store 1357 the component names leading up to and including the file system 1358 object in question. With these names, the client should be able to 1359 recover by finding a filehandle in the name space that is still 1360 available or by starting at the root of the server's file system name 1361 space. 1363 If the expired filehandle refers to an object that has been removed 1364 from the file system, obviously the client will not be able to 1365 recover from the expired filehandle. 1367 It is also possible that the expired filehandle refers to a file that 1368 has been renamed. If the file was renamed by another client, again 1369 it is possible that the original client will not be able to recover. 1370 However, in the case that the client itself is renaming the file and 1371 the file is open, it is possible that the client may be able to 1372 recover. The client can determine the new path name based on the 1373 processing of the rename request. The client can then regenerate the 1374 new filehandle based on the new path name. The client could also use 1375 the compound operation mechanism to construct a set of operations 1376 like: 1377 RENAME A B 1378 LOOKUP B 1379 GETFH 1381 Draft Specification NFS version 4 Protocol February 2000 1383 5. File Attributes 1385 To meet the requirements of extensibility and increased 1386 interoperability with non-Unix platforms, attributes must be handled 1387 in a flexible manner. The NFS Version 3 fattr3 structure contains a 1388 fixed list of attributes that not all clients and servers are able to 1389 support or care about. The fattr3 structure can not be extended as 1390 new needs arise and it provides no way to indicate non-support. With 1391 the NFS Version 4 protocol, the client will be able to ask what 1392 attributes the server supports and will be able to request only those 1393 attributes in which it is interested. 1395 To this end, attributes will be divided into three groups: mandatory, 1396 recommended, and named. Both mandatory and recommended attributes 1397 are supported in the NFS version 4 protocol by a specific and well- 1398 defined encoding and are identified by number. They are requested by 1399 setting a bit in the bit vector sent in the GETATTR request; the 1400 server response includes a bit vector to list what attributes were 1401 returned in the response. New mandatory or recommended attributes 1402 may be added to the NFS protocol between major revisions by 1403 publishing a standards-track RFC which allocates a new attribute 1404 number value and defines the encoding for the attribute. See the 1405 section "Minor Versioning" for further discussion. 1407 Named attributes are accessed by the new OPENATTR operation, which 1408 accesses a hidden directory of attributes associated with a file 1409 system object. OPENATTR takes a filehandle for the object and 1410 returns the filehandle for the attribute hierarchy. The filehandle 1411 for the named attributes is a directory object accessible by LOOKUP 1412 or READDIR and contains files whose names represent the named 1413 attributes and whose data bytes are the value of the attribute. For 1414 example: 1416 LOOKUP "foo" ; look up file 1417 GETATTR attrbits 1418 OPENATTR ; access foo's named attributes 1419 LOOKUP "x11icon" ; look up specific attribute 1420 READ 0,4096 ; read stream of bytes 1422 Named attributes are intended for data needed by applications rather 1423 than by an NFS client implementation. NFS implementors are strongly 1424 encouraged to define their new attributes as recommended attributes 1425 by bringing them to the IETF standards-track process. 1427 The set of attributes which are classified as mandatory is 1428 deliberately small since servers must do whatever it takes to support 1430 Draft Specification NFS version 4 Protocol February 2000 1432 them. The recommended attributes may be unsupported; though a server 1433 should support as many as it can. Attributes are deemed mandatory if 1434 the data is both needed by a large number of clients and is not 1435 otherwise reasonably computable by the client when support is not 1436 provided on the server. 1438 5.1. Mandatory Attributes 1440 These MUST be supported by every NFS Version 4 client and server in 1441 order to ensure a minimum level of interoperability. The server must 1442 store and return these attributes and the client must be able to 1443 function with an attribute set limited to these attributes. With 1444 just the mandatory attributes some client functionality may be 1445 impaired or limited in some ways. A client may ask for any of these 1446 attributes to be returned by setting a bit in the GETATTR request and 1447 the server must return their value. 1449 5.2. Recommended Attributes 1451 These attributes are understood well enough to warrant support in the 1452 NFS Version 4 protocol. However, they may not be supported on all 1453 clients and servers. A client may ask for any of these attributes to 1454 be returned by setting a bit in the GETATTR request but must handle 1455 the case where the server does not return them. A client may ask for 1456 the set of attributes the server supports and should not request 1457 attributes the server does not support. A server should be tolerant 1458 of requests for unsupported attributes and simply not return them 1459 rather than considering the request an error. It is expected that 1460 servers will support all attributes they comfortably can and only 1461 fail to support attributes which are difficult to support in their 1462 operating environments. A server should provide attributes whenever 1463 they don't have to "tell lies" to the client. For example, a file 1464 modification time should be either an accurate time or should not be 1465 supported by the server. This will not always be comfortable to 1466 clients but it seems that the client has a better ability to 1467 fabricate or construct an attribute or do without the attribute. 1469 5.3. Named Attributes 1471 These attributes are not supported by direct encoding in the NFS 1472 Version 4 protocol but are accessed by string names rather than 1473 numbers and correspond to an uninterpreted stream of bytes which are 1474 stored with the file system object. The name space for these 1475 attributes may be accessed by using the OPENATTR operation. The 1476 OPENATTR operation returns a filehandle for a virtual "attribute 1478 Draft Specification NFS version 4 Protocol February 2000 1480 directory" and further perusal of the name space may be done using 1481 READDIR and LOOKUP operations on this filehandle. Named attributes 1482 may then be examined or changed by normal READ and WRITE and CREATE 1483 operations on the filehandles returned from READDIR and LOOKUP. 1484 Named attributes may have attributes. 1486 It is recommended that servers support arbitrary named attributes. A 1487 client should not depend on the ability to store any named attributes 1488 in the server's file system. If a server does support named 1489 attributes, a client which is also able to handle them should be able 1490 to copy a file's data and meta-data with complete transparency from 1491 one location to another; this would imply that names allowed for 1492 regular directory entries are valid for named attribute names as 1493 well. 1495 Names of attributes will not be controlled by this document or other 1496 IETF standards track documents. See the section "IANA 1497 Considerations" for further discussion. 1499 Draft Specification NFS version 4 Protocol February 2000 1501 5.4. Mandatory Attributes - Definitions 1503 Name # DataType Access Description 1504 ___________________________________________________________________ 1505 supp_attr 0 bitmap READ The bit vector which 1506 would retrieve all 1507 mandatory and 1508 recommended attributes 1509 that are supported for 1510 this object. 1512 object_type 1 nfs4_ftype READ The type of the object 1513 (file, directory, 1514 symlink) 1516 fh_expire_type 2 uint32 READ Server uses this to 1517 specify filehandle 1518 expiration behavior to 1519 the client. See the 1520 section "Filehandles" 1521 for additional 1522 description. 1524 change 3 uint64 READ A value created by the 1525 server that the client 1526 can use to determine 1527 if file data, 1528 directory contents or 1529 attributes of the 1530 object have been 1531 modified. The server 1532 may return the 1533 object's time_modify 1534 attribute for this 1535 attribute's value but 1536 only if the file 1537 system object can not 1538 be updated more 1539 frequently than the 1540 resolution of 1541 time_modify. 1543 object_size 4 uint64 R/W The size of the object 1544 in bytes. 1546 Draft Specification NFS version 4 Protocol February 2000 1548 link_support 5 boolean READ Does the object's file 1549 system supports hard 1550 links? 1552 symlink_support 6 boolean READ Does the object's file 1553 system supports 1554 symbolic links? 1556 named_attr 7 boolean READ Does this object have 1557 named attributes? 1559 fsid 8 fsid4 READ Unique file system 1560 identifier for the 1561 file system holding 1562 this object. fsid 1563 contains major and 1564 minor components each 1565 of which are uint64. 1567 unique_handles 9 boolean READ Are two distinct 1568 filehandles guaranteed 1569 to refer to two 1570 different file system 1571 objects? 1573 lease_time 10 nfs_lease4 READ Duration of leases at 1574 server in seconds. 1576 rdattr_error 11 enum READ Error returned from 1577 getattr during 1578 readdir. 1580 Draft Specification NFS version 4 Protocol February 2000 1582 5.5. Recommended Attributes - Definitions 1584 Name # Data Type Access Description 1585 _____________________________________________________________________ 1586 ACL 12 nfsace4<> R/W The access control 1587 list for the object. 1589 aclsupport 13 uint32 READ Indicates what types 1590 of ACLs are supported 1591 on the current file 1592 system. 1594 archive 14 boolean R/W Whether or not this 1595 file has been 1596 archived since the 1597 time of last 1598 modification 1599 (deprecated in favor 1600 of backup_time). 1602 cansettime 15 boolean READ Whether or not this 1603 object's file system 1604 can fill in the times 1605 on a SETATTR request 1606 without an explicit 1607 time. 1609 case_insensitive 16 boolean READ Are filename 1610 comparisons on this 1611 file system case 1612 insensitive? 1614 case_preserving 17 boolean READ Is filename case on 1615 this file system 1616 preserved? 1618 Draft Specification NFS version 4 Protocol February 2000 1620 chown_restricted 18 boolean READ If TRUE, the server 1621 will reject any 1622 request to change 1623 either the owner or 1624 the group associated 1625 with a file if the 1626 caller is not a 1627 privileged user (for 1628 example, "root" in 1629 Unix operating 1630 environments or in NT 1631 the "Take Ownership" 1632 privilege) 1634 filehandle 19 nfs4_fh READ The filehandle of 1635 this object 1636 (primarily for 1637 readdir requests). 1639 fileid 20 uint64 READ A number uniquely 1640 identifying the file 1641 within the file 1642 system. 1644 files_avail 21 uint64 READ File slots available 1645 to this user on the 1646 file system 1647 containing this 1648 object - this should 1649 be the smallest 1650 relevant limit. 1652 files_free 22 uint64 READ Free file slots on 1653 the file system 1654 containing this 1655 object - this should 1656 be the smallest 1657 relevant limit. 1659 files_total 23 uint64 READ Total file slots on 1660 the file system 1661 containing this 1662 object. 1664 Draft Specification NFS version 4 Protocol February 2000 1666 fs_locations 24 fs_locations READ Locations where this 1667 file system may be 1668 found. If the server 1669 returns NFS4ERR_MOVED 1670 as an error, this 1671 attribute must be 1672 supported. 1674 hidden 25 boolean R/W Is file considered 1675 hidden with respect 1676 to the WIN32 API? 1678 homogeneous 26 boolean READ Whether or not this 1679 object's file system 1680 is homogeneous, i.e. 1681 whether pathconf is 1682 the same for all file 1683 system objects. 1685 maxfilesize 27 uint64 READ Maximum supported 1686 file size for the 1687 file system of this 1688 object. 1690 maxlink 28 uint32 READ Maximum number of 1691 links for this 1692 object. 1694 maxname 29 uint32 READ Maximum filename size 1695 supported for this 1696 object. 1698 maxread 30 uint64 READ Maximum read size 1699 supported for this 1700 object. 1702 Draft Specification NFS version 4 Protocol February 2000 1704 maxwrite 31 uint64 READ Maximum write size 1705 supported for this 1706 object. This 1707 attribute SHOULD be 1708 supported if the file 1709 is writable. Lack of 1710 this attribute can 1711 lead to the client 1712 either wasting 1713 bandwidth or not 1714 receiving the best 1715 performance. 1717 mime_type 32 utf8<> R/W MIME body 1718 type/subtype of this 1719 object. 1721 mode 33 mode4 R/W Unix-style permission 1722 bits for this object 1723 (deprecated in favor 1724 of ACLs) 1726 no_trunc 34 boolean READ If a name longer than 1727 name_max is used, 1728 will an error be 1729 returned or will the 1730 name be truncated? 1732 numlinks 35 uint32 READ Number of links to 1733 this object. 1735 owner 36 utf8<> R/W The string name of 1736 the owner of this 1737 object. 1739 owner_group 37 utf8<> R/W The string name of 1740 the group of the 1741 owner of this object. 1743 quota_hard 38 uint64 READ For definition see 1744 "Quota Attributes" 1745 section below. 1747 quota_soft 39 uint64 READ For definition see 1748 "Quota Attributes" 1749 section below. 1751 Draft Specification NFS version 4 Protocol February 2000 1753 quota_used 40 uint64 READ For definition see 1754 "Quota Attributes" 1755 section below. 1757 rawdev 41 specdata4 READ Raw device 1758 identifier. 1760 space_avail 42 uint64 READ Disk space in bytes 1761 available to this 1762 user on the file 1763 system containing 1764 this object - this 1765 should be the 1766 smallest relevant 1767 limit. 1769 space_free 43 uint64 READ Free disk space in 1770 bytes on the file 1771 system containing 1772 this object - this 1773 should be the 1774 smallest relevant 1775 limit. 1777 space_total 44 uint64 READ Total disk space in 1778 bytes on the file 1779 system containing 1780 this object. 1782 space_used 45 uint64 READ Number of file system 1783 bytes allocated to 1784 this object. 1786 system 46 boolean R/W Is this file is a 1787 system file with 1788 respect to the WIN32 1789 API? 1791 time_access 47 nfstime4 READ The time of last 1792 access to the object. 1794 time_access_set 48 settime4 WRITE Set the time of last 1795 access to the object. 1796 SETATTR use only. 1798 time_backup 49 nfstime4 R/W The time of last 1799 backup of the object. 1801 Draft Specification NFS version 4 Protocol February 2000 1803 time_create 50 nfstime4 R/W The time of creation 1804 of the object. This 1805 attribute does not 1806 have any relation to 1807 the traditional Unix 1808 file attribute 1809 "ctime" or "change 1810 time". 1812 time_delta 51 nfstime4 READ Smallest useful 1813 server time 1814 granularity. 1816 time_metadata 52 nfstime4 R/W The time of last 1817 meta-data 1818 modification of the 1819 object. 1821 time_modify 53 nfstime4 READ The time of last 1822 modification to the 1823 object. 1825 time_modify_set 54 settime4 WRITE Set the time of last 1826 modification to the 1827 object. SETATTR use 1828 only. 1830 5.6. Interpreting owner and owner_group 1832 The recommended attributes "owner" and "owner_group" are represented 1833 in terms of a UTF-8 string. To avoid a representation that is tied 1834 to a particular underlying implementation at the client or server, 1835 the use of the UTF-8 string has been chosen. Note that section 6.1 1836 of [RFC2624] provides additional rationale. It is expected that the 1837 client and server will have their own local representation of owner 1838 and owner_group that is used for local storage or presentation to the 1839 end user. Therefore, it is expected that when these attributes are 1840 transferred between the client and server that the local 1841 representation is translated to a syntax of the form 1842 "user@dns_domain". This will allow for a client and server that do 1843 not use the same local representation the ability to translate to a 1844 common syntax that can be interpreted by both. 1846 The translation is not specified as part of the protocol. This 1847 allows various solutions to be employed. For example, a local 1849 Draft Specification NFS version 4 Protocol February 2000 1851 translation table may be consulted that maps between a numeric id to 1852 the user@dns_domain syntax. A name service may also be used to 1853 accomplish the translation. The "dns_domain" portion of the owner 1854 string is meant to be a DNS domain name. For example, user@ietf.org. 1856 In the case where there is no translation available to the client or 1857 server, the attribute value must be constructed without the "@". 1858 Therefore, the absence of the @ from the owner or owner_group 1859 attribute signifies that no translation was available and the 1860 receiver of the attribute should not place any special meaning with 1861 the attribute value. Even though the attribute value can not be 1862 translated, it may still be useful. In the case of a client, the 1863 attribute string may be used for local display of ownership. 1865 5.7. Quota Attributes 1867 For the attributes related to file system quotas, the following 1868 definitions apply: 1870 quota_avail_soft 1871 The value in bytes which represents the amount of additional 1872 disk space that can be allocated to this file or directory 1873 before the user may reasonably be warned. It is understood that 1874 this space may be consumed by allocations to other files or 1875 directories though there is a rule as to which other files or 1876 directories. 1878 quota_avail_hard 1879 The value in bytes which represent the amount of additional disk 1880 space beyond the current allocation that can be allocated to 1881 this file or directory before further allocations will be 1882 declined. It is understood that this space may be consumed by 1883 allocations to other files or directories. 1885 quota_used 1886 The value in bytes which represent the amount of disc space used 1887 by this file or directory and possibly a number of other similar 1888 files or directories, where the set of "similar" meets at least 1889 the criterion that allocating space to any file or directory in 1890 the set will reduce the "quota_avail_hard" of every other file 1891 or directory in the set. 1893 Note that there may be a number of distinct but overlapping sets 1894 of files or directories for which a quota_used value is 1895 maintained. E.g. "all files with a given owner", "all files with 1897 Draft Specification NFS version 4 Protocol February 2000 1899 a given group owner". etc. 1901 The server is at liberty to choose any of those sets but should 1902 do so in a repeatable way. The rule may be configured per- 1903 filesystem or may be "choose the set with the smallest quota". 1905 5.8. Access Control Lists 1907 The NFS ACL attribute is an array of access control entries (ACE). 1908 There are various access control entry types. The server is able to 1909 communicate which ACE types are supported by returning the 1910 appropriate value within the aclsupport attribute. The types of ACEs 1911 are defined as follows: 1913 Type Description 1914 _____________________________________________________ 1915 ALLOW Explicitly grants the access defined in 1916 acemask4 to the file or directory. 1918 DENY Explicitly denies the access defined in 1919 acemask4 to the file or directory. 1921 AUDIT LOG (system dependant) any access 1922 attempt to a file or directory which 1923 uses any of the access methods specified 1924 in acemask4. 1926 ALARM Generate a system ALARM (system 1927 dependant) when any access attempt is 1928 made to a file or directory for the 1929 access methods specified in acemask4. 1931 The NFS ACE attribute is defined as follows: 1933 typedef uint32_t acetype4; 1934 typedef uint32_t aceflag4; 1935 typedef uint32_t acemask4; 1937 struct nfsace4 { 1938 acetype4 type; 1939 aceflag4 flag; 1940 acemask4 access_mask; 1941 utf8string who; 1942 }; 1944 To determine if an ACCESS or OPEN request succeeds each nfsace4 entry 1945 is processed in order by the server. Only ACEs which have a "who" 1947 Draft Specification NFS version 4 Protocol February 2000 1949 that matches the requester are considered. Each ACE is processed 1950 until all of the bits of the requester's access have been ALLOWED. 1951 Once a bit (see below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it 1952 is no longer considered in the processing of later ACEs. If an 1953 ACCESS_DENIED_ACE is encountered where the requester's mode still has 1954 unALLOWED bits in common with the "access_mask" of the ACE, the 1955 request is denied. 1957 The bitmask constants used to represent the above definitions within 1958 the aclsupport attribute are as follows: 1960 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 1961 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 1962 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 1963 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 1965 5.8.1. ACE type 1967 The semantics of the "type" field follow the descriptions provided 1968 above. 1970 The bitmask constants used to for the type field are as follows: 1972 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 1973 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 1974 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 1975 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 1977 5.8.2. ACE flag 1979 The "flag" field contains values based on the following descriptions. 1981 ACE4_FILE_INHERIT_ACE 1983 Can be placed on a directory and indicates that this ACE should be 1984 added to each new non-directory file created. 1986 ACE4_DIRECTORY_INHERIT_ACE 1988 Can be placed on a directory and indicates that this ACE should be 1989 added to each new directory created. 1991 ACE4_INHERIT_ONLY_ACE 1993 Draft Specification NFS version 4 Protocol February 2000 1995 Can be placed on a directory but does not apply to the directory, 1996 only to newly created files/directories as specified by the above two 1997 flags. 1999 ACE4_NO_PROPAGATE_INHERIT_ACE 2001 Can be placed on a directory. Normally when a new directory is 2002 created and an ACE exists on the parent directory which is marked 2003 ACL4_DIRECTORY_INHERIT_ACE, two ACEs are placed on the new directory. 2004 One for the directory itself and one which is an inheritable ACE for 2005 newly created directories. This flag tells the server to not place 2006 an ACE on the newly created directory which is inheritable by 2007 subdirectories of the created directory. 2009 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 2011 ACL4_FAILED_ACCESS_ACE_FLAG 2013 Both indicate for AUDIT and ALARM which state to log the event. On 2014 every ACCESS or OPEN call which occurs on a file or directory which 2015 has an ACL that is of type ACE4_SYSTEM_AUDIT_ACE_TYPE or 2016 ACE4_SYSTEM_ALARM_ACE_TYPE, the attempted access is compared to the 2017 ace4mask of these ACLs. If the access is a subset of ace4mask and the 2018 identifier match, an AUDIT trail or an ALARM is generated. By 2019 default this happens regardless of the success or failure of the 2020 ACCESS or OPEN call. 2022 The flag ACE4_SUCCESSFUL_ACCESS_ACE_FLAG only produces the AUDIT or 2023 ALARM if the ACCESS or OPEN call is successful. The 2024 ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS 2025 or OPEN call fails. 2027 ACE4_IDENTIFIER_GROUP 2029 Indicates that the "who" refers to a GROUP as defined under Unix. 2031 The bitmask constants used to for the flag field are as follows: 2033 const ACE4_FILE_INHERIT_ACE = 0x00000001; 2034 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 2035 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 2036 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 2037 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 2039 Draft Specification NFS version 4 Protocol February 2000 2041 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 2042 const ACE4_IDENTIFIER_GROUP = 0x00000040; 2044 5.8.3. ACE Access Mask 2046 The access_mask field contains values based on the following: 2048 Access Description 2049 _______________________________________________________________ 2050 READ_DATA Permission to read the data of the file 2051 LIST_DIRECTORY Permission to list the contents of a 2052 directory 2053 WRITE_DATA Permission to modify the file's data 2054 ADD_FILE Permission to add a new file to a 2055 directory 2056 APPEND_DATA Permission to append data to a file 2057 ADD_SUBDIRECTORY Permission to create a subdirectory to a 2058 directory 2059 READ_NAMED_ATTRS Permission to read the named attributes 2060 of a file 2061 WRITE_NAMED_ATTRS Permission to write the named attributes 2062 of a file 2063 EXECUTE Permission to execute a file 2064 DELETE_CHILD Permission to delete a file or directory 2065 within a directory 2066 READ_ATTRIBUTES The ability to read basic attributes 2067 (non-acls) of a file 2068 WRITE_ATTRIBUTES Permission to change basic attributes 2069 (non-acls) of a file 2070 DELETE Permission to Delete the File 2071 READ_ACL Permission to Read the ACL 2072 WRITE_ACL Permission to Write the ACL 2073 WRITE_OWNER Permission to change the owner 2074 SYNCHRONIZE Permission to access file locally at the 2075 server with synchronous reads and writes 2077 The bitmask constants used to for the access mask field are as 2078 follows: 2080 const ACE4_READ_DATA = 0x00000001; 2081 const ACE4_LIST_DIRECTORY = 0x00000001; 2082 const ACE4_WRITE_DATA = 0x00000002; 2083 const ACE4_ADD_FILE = 0x00000002; 2084 const ACE4_APPEND_DATA = 0x00000004; 2085 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 2087 Draft Specification NFS version 4 Protocol February 2000 2089 const ACE4_READ_NAMED_ATTRS = 0x00000008; 2090 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 2091 const ACE4_EXECUTE = 0x00000020; 2092 const ACE4_DELETE_CHILD = 0x00000040; 2093 const ACE4_READ_ATTRIBUTES = 0x00000080; 2094 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 2096 const ACE4_DELETE = 0x00010000; 2097 const ACE4_READ_ACL = 0x00020000; 2098 const ACE4_WRITE_ACL = 0x00040000; 2099 const ACE4_WRITE_OWNER = 0x00080000; 2100 const ACE4_SYNCHRONIZE = 0x00100000; 2102 5.8.4. ACE who 2104 There are several special identifiers ("who") which need to be 2105 understood universally. Some of these identifiers cannot be 2106 understood when an NFS client accesses the server, but have meaning 2107 when a local process accesses the file. The ability to display and 2108 modify these permissions is permitted over NFS. 2110 Who Description 2111 _______________________________________________________________ 2112 "OWNER" The owner of the file. 2113 "GROUP" The group associated with the file. 2114 "EVERYONE" The world. 2115 "INTERACTIVE" Accessed from an interactive terminal. 2116 "NETWORK" Accessed via the network. 2117 "DIALUP" Accessed as a dialup user to the server. 2118 "BATCH" Accessed from a batch job. 2119 "ANONYMOUS" Accessed without any authentication. 2120 "AUTHENTICATED" Any authenticated user (opposite of 2121 ANONYMOUS) 2122 "SERVICE" Access from a system service. 2124 To avoid conflict, these special identitifers are distinguish by an 2125 appended "@" and should appear in the form "xxxx@" (note: no domain 2126 name after the "@"). For example: ANONYMOUS@. 2128 Draft Specification NFS version 4 Protocol February 2000 2130 6. File System Migration and Replication 2132 With the use of the recommended attribute "fs_locations", the NFS 2133 version 4 server has a method of providing file system migration or 2134 replication services. For the purposes of migration and replication, 2135 a file system will be defined as all files that share a given fsid 2136 (both major and minor values are the same). 2138 The fs_locations attribute provides a list of file system locations. 2139 These locations are specified by providing the server name (either 2140 DNS domain or IP address) and the path name representing the root of 2141 the file system. Depending on the type of service being provided, 2142 the list will provide a new location or a set of alternate locations 2143 for the file system. The client will use this information to 2144 redirect its requests to the new server. 2146 6.1. Replication 2148 It is expected that file system replication will be used in the case 2149 of read-only data. Typically, the file system will be replicated on 2150 two or more servers. The fs_locations attribute will provide the 2151 list of these locations to the client. On first access of the file 2152 system, the client should obtain the value of the fs_locations 2153 attribute. If, in the future, the client finds the server 2154 unresponsive, the client may attempt to use another server specified 2155 by fs_locations. 2157 If applicable, the client must take the appropriate steps to recover 2158 valid filehandles from the new server. This is described in more 2159 detail in the following sections. 2161 6.2. Migration 2163 File system migration is used to move a file system from one server 2164 to another. Migration is typically used for a file system that is 2165 writable and has a single copy. The expected use of migration is for 2166 load balancing or general resource reallocation. The protocol does 2167 not specify how the file system will be moved between servers. This 2168 server-to-server transfer mechanism is left to the server 2169 implementor. However, the method used to communicate the migration 2170 event between client and server is specified here. 2172 Once the servers participating in the migration have completed the 2173 move of the file system, the error NFS4ERR_MOVED will be returned for 2174 subsequent requests received by the original server. The 2175 NFS4ERR_MOVED error is returned for all operations except GETATTR. 2177 Draft Specification NFS version 4 Protocol February 2000 2179 Upon receiving the NFS4ERR_MOVED error, the client will obtain the 2180 value of the fs_locations attribute. The client will then use the 2181 contents of the attribute to redirect its requests to the specified 2182 server. To facilitate the use of GETATTR, operations such as PUTFH 2183 must also be accepted by the server for the migrated file system's 2184 filehandles. Note that if the server returns NFS4ERR_MOVED, the 2185 server MUST support the fs_locations attribute. 2187 If the client requests more attributes than fs_locations, the server 2188 may return fs_locations only. This is to be expected since the 2189 server has migrated the file system and may not have a method of 2190 obtaining additional attribute data. 2192 The server implementor needs to be careful in developing a migration 2193 solution. The server must consider all of the state information 2194 clients may have outstanding at the server. This includes but is not 2195 limited to locking/share state, delegation state, and asynchronous 2196 file writes which are represented by WRITE and COMMIT verifiers. The 2197 server should strive to minimize the impact on its clients during and 2198 after the migration process. 2200 6.3. Interpretation of the fs_locations Attribute 2202 The fs_location attribute is structured in the following way: 2204 struct fs_location { 2205 utf8string server<>; 2206 pathname4 rootpath; 2207 }; 2209 struct fs_locations { 2210 pathname4 fs_root; 2211 fs_location locations<>; 2212 }; 2214 The fs_location struct is used to represent the location of a file 2215 system by providing a server name and the path to the root of the 2216 file system. For a multi-homed server or a set of servers that use 2217 the same rootpath, an array of server names may be provided. An 2218 entry in the server array is an UTF8 string and represents one of a 2219 traditional DNS host name, IPv4 address, or IPv6 address. It is not 2220 a requirement that all servers that share the same rootpath be listed 2221 in one fs_location struct. The array of server names is provided for 2222 convenience. Servers that share the same rootpath may also be listed 2223 in separate fs_location entries in the fs_locations attribute. 2225 The fs_locations struct and attribute then contains an array of 2227 Draft Specification NFS version 4 Protocol February 2000 2229 locations. Since the name space of each server may be constructed 2230 differently, the "fs_root" field is provided. The path represented 2231 by fs_root represents the location of the file system in the server's 2232 name space. Therefore, the fs_root path is only associated with the 2233 server from which the fs_locations attribute was obtained. The 2234 fs_root path is meant to aid the client in locating the file system 2235 at the various servers listed. 2237 As an example, there is a replicated file system located at two 2238 servers (servA and servB). At servA the file system is located at 2239 path "/a/b/c". At servB the file system is located at path "/x/y/z". 2240 In this example the client accesses the file system first at servA 2241 with a multi-component lookup path of "/a/b/c/d". Since the client 2242 used a multi-component lookup to obtain the filehandle at "/a/b/c/d", 2243 it is unaware that the file system's root is located in servA's name 2244 space at "/a/b/c". When the client switches to servB, it will need 2245 to determine that the directory it first referenced at servA is now 2246 represented by the path "/x/y/z/d" on servB. To facilitate this, the 2247 fs_locations attribute provided by servA would have a fs_root value 2248 of "/a/b/c" and two entries in fs_location. One entry in fs_location 2249 will be for itself (servA) and the other will be for servB with a 2250 path of "/x/y/z". With this information, the client is able to 2251 substitute "/x/y/z" for the "/a/b/c" at the beginning of its access 2252 path and construct "/x/y/z/d" to use for the new server. 2254 6.4. Filehandle Recovery for Migration or Replication 2256 Filehandles for file systems that are replicated or migrated 2257 generally have the same semantics as for file systems that are not 2258 replicated or migrated. For example, if a file system has persistent 2259 filehandles and it is migrated to another server, the filehandle 2260 values for the file system will be valid at the new server. 2262 For volatile filehandles, the servers involved likely do not have a 2263 mechanism to transfer filehandle format and content between 2264 themselves. Therefore, a server may have difficulty in determining 2265 if a volatile filehandle from an old server should return an error of 2266 NFS4ERR_FHEXPIRED. Therefore, the client is informed, with the use 2267 of the fh_expire_type attribute, whether volatile filehandles will 2268 expire at the migration or replication event. If the bit 2269 FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client 2270 must treat the volatile filehandle as if the server had returned the 2271 NFS4ERR_FHEXPIRED error. At the migration or replication event in 2272 the presence of the FH4_VOL_MIGRATION bit, the client will not 2273 present the original or old volatile file handle to the new server. 2274 The client will start its communication with the new server by 2275 recovering its filehandles using the saved file names. 2277 Draft Specification NFS version 4 Protocol February 2000 2279 7. NFS Server Name Space 2281 7.1. Server Exports 2283 On a UNIX server the name space describes all the files reachable by 2284 pathnames under the root directory or "/". On a Windows NT server 2285 the name space constitutes all the files on disks named by mapped 2286 disk letters. NFS server administrators rarely make the entire 2287 server's file system name space available to NFS clients. More often 2288 portions of the name space are made available via an "export" 2289 feature. In previous versions of the NFS protocol, the root 2290 filehandle for each export is obtained through the MOUNT protocol; 2291 the client sends a string that identifies the export of name space 2292 and the server returns the root filehandle for it. The MOUNT 2293 protocol supports an EXPORTS procedure that will enumerate the 2294 server's exports. 2296 7.2. Browsing Exports 2298 The NFS version 4 protocol provides a root filehandle that clients 2299 can use to obtain filehandles for these exports via a multi-component 2300 LOOKUP. A common user experience is to use a graphical user 2301 interface (perhaps a file "Open" dialog window) to find a file via 2302 progressive browsing through a directory tree. The client must be 2303 able to move from one export to another export via single-component, 2304 progressive LOOKUP operations. 2306 This style of browsing is not well supported by the NFS version 2 and 2307 3 protocols. The client expects all LOOKUP operations to remain 2308 within a single server file system. For example, the device 2309 attribute will not change. This prevents a client from taking name 2310 space paths that span exports. 2312 An automounter on the client can obtain a snapshot of the server's 2313 name space using the EXPORTS procedure of the MOUNT protocol. If it 2314 understands the server's pathname syntax, it can create an image of 2315 the server's name space on the client. The parts of the name space 2316 that are not exported by the server are filled in with a "pseudo file 2317 system" that allows the user to browse from one mounted file system 2318 to another. There is a drawback to this representation of the 2319 server's name space on the client: it is static. If the server 2320 administrator adds a new export the client will be unaware of it. 2322 Draft Specification NFS version 4 Protocol February 2000 2324 7.3. Server Pseudo File System 2326 NFS version 4 servers avoid this name space inconsistency by 2327 presenting all the exports within the framework of a single server 2328 name space. An NFS version 4 client uses LOOKUP and READDIR 2329 operations to browse seamlessly from one export to another. Portions 2330 of the server name space that are not exported are bridged via a 2331 "pseudo file system" that provides a view of exported directories 2332 only. A pseudo file system has a unique fsid and behaves like a 2333 normal, read only file system. 2335 Based on the construction of the server's name space, it is possible 2336 that multiple pseudo file systems may exist. For example, 2338 /a pseudo file system 2339 /a/b real file system 2340 /a/b/c pseudo file system 2341 /a/b/c/d real file system 2343 Each of the pseudo file systems are consider separate entities and 2344 therefore will have a unique fsid. 2346 7.4. Multiple Roots 2348 The DOS and Windows operating environments are sometimes described as 2349 having "multiple roots". File systems are commonly represented as 2350 disk letters. MacOS represents file systems as top level names. NFS 2351 version 4 servers for these platforms can construct a pseudo file 2352 system above these root names so that disk letters or volume names 2353 are simply directory names in the pseudo root. 2355 7.5. Filehandle Volatility 2357 The nature of the server's pseudo file system is that it is a logical 2358 representation of file system(s) available from the server. 2359 Therefore, the pseudo file system is most likely constructed 2360 dynamically when the server is first instantiated. It is expected 2361 that the pseudo file system may not have an on disk counterpart from 2362 which persistent filehandles could be constructed. Even though it is 2363 preferable that the server provide persistent filehandles for the 2364 pseudo file system, the NFS client should expect that pseudo file 2365 system filehandles are volatile. This can be confirmed by checking 2366 the associated "persistent_fh" attribute for those filehandles in 2367 question. If the filehandles are volatile, the NFS client must be 2368 prepared to recover a filehandle value (e.g. with a multi-component 2369 LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 2371 Draft Specification NFS version 4 Protocol February 2000 2373 7.6. Exported Root 2375 If the server's root file system is exported, one might conclude that 2376 a pseudo-file system is not needed. This would be wrong. Assume the 2377 following file systems on a server: 2379 / disk1 (exported) 2380 /a disk2 (not exported) 2381 /a/b disk3 (exported) 2383 Because disk2 is not exported, disk3 cannot be reached with simple 2384 LOOKUPs. The server must bridge the gap with a pseudo-file system. 2386 7.7. Mount Point Crossing 2388 The server file system environment may be constructed in such a way 2389 that one file system contains a directory which is 'covered' or 2390 mounted upon by a second file system. For example: 2392 /a/b (file system 1) 2393 /a/b/c/d (file system 2) 2395 The pseudo file system for this server may be constructed to look 2396 like: 2398 / (place holder/not exported) 2399 /a/b (file system 1) 2400 /a/b/c/d (file system 2) 2402 It is the server's responsibility to present the pseudo file system 2403 that is complete to the client. If the client sends a lookup request 2404 for the path "/a/b/c/d", the server's response is the filehandle of 2405 the file system "/a/b/c/d". In previous versions of the NFS 2406 protocol, the server would respond with the directory "/a/b/c/d" 2407 within the file system "/a/b". 2409 The NFS client will be able to determine if it crosses a server mount 2410 point by a change in the value of the "fsid" attribute. 2412 7.8. Security Policy and Name Space Presentation 2414 The application of the server's security policy needs to be carefully 2415 considered by the implementor. One may choose to limit the 2416 viewability of portions of the pseudo file system based on the 2417 server's perception of the client's ability to authenticate itself 2418 properly. However with the support of multiple security mechanisms 2420 Draft Specification NFS version 4 Protocol February 2000 2422 and the ability to negotiate the appropriate use of these mechanisms, 2423 the server is unable to properly determine if a client will be able 2424 to authenticate itself. If, based on its policies, the server 2425 chooses to limit the contents of the pseudo file system, the server 2426 may effectively hide file systems from a client that may otherwise 2427 have legitimate access. 2429 Draft Specification NFS version 4 Protocol February 2000 2431 8. File Locking and Share Reservations 2433 Integrating locking into the NFS protocol necessarily causes it to be 2434 state-full. With the inclusion of "share" file locks the protocol 2435 becomes substantially more dependent on state than the traditional 2436 combination of NFS and NLM [XNFS]. There are three components to 2437 making this state manageable: 2439 o Clear division between client and server 2441 o Ability to reliably detect inconsistency in state between client 2442 and server 2444 o Simple and robust recovery mechanisms 2446 In this model, the server owns the state information. The client 2447 communicates its view of this state to the server as needed. The 2448 client is also able to detect inconsistent state before modifying a 2449 file. 2451 To support Win32 "share" locks it is necessary to atomically OPEN or 2452 CREATE files. Having a separate share/unshare operation would not 2453 allow correct implementation of the Win32 OpenFile API. In order to 2454 correctly implement share semantics, the previous NFS protocol 2455 mechanisms used when a file is opened or created (LOOKUP, CREATE, 2456 ACCESS) need to be replaced. The NFS version 4 protocol has an OPEN 2457 operation that subsumes the functionality of LOOKUP, CREATE, and 2458 ACCESS. However, because many operations require a filehandle, the 2459 traditional LOOKUP is preserved to map a file name to filehandle 2460 without establishing state on the server. The policy of granting 2461 access or modifying files is managed by the server based on the 2462 client's state. These mechanisms can implement policy ranging from 2463 advisory only locking to full mandatory locking. 2465 8.1. Locking 2467 It is assumed that manipulating a lock is rare when compared to READ 2468 and WRITE operations. It is also assumed that crashes and network 2469 partitions are relatively rare. Therefore it is important that the 2470 READ and WRITE operations have a lightweight mechanism to indicate if 2471 they possess a held lock. A lock request contains the heavyweight 2472 information required to establish a lock and uniquely define the lock 2473 owner. 2475 The following sections describe the transition from the heavy weight 2476 information to the eventual stateid used for most client and server 2477 locking and lease interactions. 2479 Draft Specification NFS version 4 Protocol February 2000 2481 8.1.1. Client ID 2483 For each LOCK request, the client must identify itself to the server. 2484 This is done in such a way as to allow for correct lock 2485 identification and crash recovery. Client identification is 2486 accomplished with two values. 2488 o A verifier that is used to detect client reboots. 2490 o A variable length opaque array to uniquely define a client. 2492 For an operating system this may be a fully qualified host 2493 name or IP address. For a user level NFS client it may 2494 additionally contain a process id or other unique sequence. 2496 The data structure for the Client ID would then appear as: 2498 struct nfs_client_id { 2499 opaque verifier[4]; 2500 opaque id<>; 2501 } 2503 It is possible through the mis-configuration of a client or the 2504 existence of a rogue client that two clients end up using the same 2505 nfs_client_id. This situation is avoided by "negotiating" the 2506 nfs_client_id between client and server with the use of the 2507 SETCLIENTID and SETCLIENTID_CONFIRM operations. The following 2508 describes the two scenarios of negotiation. 2510 1 Client has never connected to the server 2512 In this case the client generates an nfs_client_id and 2513 unless another client has the same nfs_client_id.id field, 2514 the server accepts the request. The server also records the 2515 principal (or principal to uid mapping) from the credential 2516 in the RPC request that contains the nfs_client_id 2517 negotiation request (SETCLIENTID operation). 2519 Two clients might still use the same nfs_client_id.id due 2520 to perhaps configuration error. For example, a High 2521 Availability configuration where the nfs_client_id.id is 2522 derived from the ethernet controller address and both 2523 systems have the same address. In this case, the result is 2524 a switched union that returns in addition to 2525 NFS4ERR_CLID_INUSE, the network address (the rpcbind netid 2526 and universal address) of the client that is using the id. 2528 Draft Specification NFS version 4 Protocol February 2000 2530 2 Client is re-connecting to the server after a client reboot 2532 In this case, the client still generates an nfs_client_id 2533 but the nfs_client_id.id field will be the same as the 2534 nfs_client_id.id generated prior to reboot. If the server 2535 finds that the principal/uid is equal to the previously 2536 "registered" nfs_client_id.id, then locks associated with 2537 the old nfs_client_id are immediately released. If the 2538 principal/uid is not equal, then this is a rogue client and 2539 the request is returned in error. For more discussion of 2540 crash recovery semantics, see the section on "Crash 2541 Recovery" 2543 To mitigate retransmission of the SETCLIENTID operation, 2544 the client and server use a confirmation step. The server 2545 returns a confirmation verifier that the client then sends 2546 to the server in the SETCLIENTID_CONFIRM operation. Once 2547 the server receives the confirmation from the client, the 2548 locking state for the client is released. 2550 In both cases, upon success, NFS4_OK is returned. To help reduce the 2551 amount of data transferred on OPEN and LOCK, the server will also 2552 return a unique 64-bit clientid value that is a shorthand reference 2553 to the nfs_client_id values presented by the client. From this point 2554 forward, the client will use the clientid to refer to itself. 2556 The clientid assigned by the server should be chosen so that it will 2557 not conflict with a clientid previously assigned by the server. This 2558 applies across server restarts or reboots. When a clientid is 2559 presented to a server and that clientid is not recognized, as would 2560 happen after a server reboot, the server will reject the request with 2561 the error NFS4ERR_STALE_CLIENTID. When this happens, the client must 2562 obtain a new clientid by use of the SETCLIENTID operation and then 2563 proceed to any other necessary recovery for the server reboot case 2564 (See the section "Server Failure and Recovery"). 2566 The client must also employ the SETCLIENTID operation when it 2567 receives a NFS4ERR_STALE_STATEID error using a stateid derived from 2568 its current clientid since this also indicates a server reboot which 2569 has invalidated the existing clientid (see the next section 2570 "nfs_lockowner and stateid Definition" for details). 2572 8.1.2. Server Release of Clientid 2574 If the server determines that the client holds no associated state 2575 for its clientid and no activity from that client has been received 2576 some long period of time, the server may choose to release the 2578 Draft Specification NFS version 4 Protocol February 2000 2580 clientid. The server may make this choice for an inactive client so 2581 that resources are not consumed by those intermittently active 2582 clients. If the client contacts the server after the this release, 2583 the server must ensure the client receives the appropriate error so 2584 that it will use the SETCLIENTID/SETCLIENTID_CONFIRM sequence to 2585 establish a new identity. It should be clear that the server must be 2586 very hesitant to release a clientid since the resultant work on the 2587 client to recover from such an event will be the same burden as if 2588 the server had failed and restarted. 2590 8.1.3. nfs_lockowner and stateid Definition 2592 When requesting a lock, the client must present to the server the 2593 clientid and an identifier for the owner of the requested lock. 2594 These two fields are referred to as the nfs_lockowner and the 2595 definition of those fields are: 2597 o A clientid returned by the server as part of the client's use of 2598 the SETCLIENTID operation. 2600 o A variable length opaque array used to uniquely define the owner 2601 of a lock managed by the client. 2603 This may be a thread id, process id, or other unique value. 2605 When the server grants the lock, it responds with a unique 64-bit 2606 stateid. The stateid is used as a shorthand reference to the 2607 nfs_lockowner, since the server will be maintaining the 2608 correspondence between them. 2610 The server is free to form the stateid in any manner that it chooses 2611 as long as it is able to recognize invalid and out-of-date stateids. 2612 This requirement includes those stateids generated by earlier 2613 instances of the server. From this, the client can be properly 2614 notified of a server restart. This notification will occur when the 2615 client presents a stateid to the server from a previous 2616 instantiation. 2618 The server must be able to distinguish the following situations and 2619 return the error as specified: 2621 o The stateid was generated by an earlier server instance (i.e. 2622 before a server reboot). The error NFS4ERR_STALE_STATEID should 2623 be returned. 2625 o The stateid was generated by the current server instance but the 2627 Draft Specification NFS version 4 Protocol February 2000 2629 stateid no longer designates the current locking state for the 2630 lockowner-file pair in question (i.e. one or more locking 2631 operations has occurred). The error NFS4ERR_OLD_STATEID should 2632 be returned. 2634 This error condition will only occur when the client issues a 2635 locking request which changes a stateid while an I/O request 2636 that uses that stateid is outstanding. 2638 o The stateid was generated by the current server instance but the 2639 stateid does not designate a locking state for any active 2640 lockowner-file pair. The error NFS4ERR_BAD_STATEID should be 2641 returned. 2643 This error condition will occur when there has been a logic 2644 error on the part of the client or server. This should not 2645 happen. 2647 One mechanism that may be used to satisfy these requirements is for 2648 the server to divide stateids into three fields: 2650 o A server verifier which uniquely designates a particular server 2651 instantiation. 2653 o An index into a table of locking-state structures. 2655 o A sequence value which is incremented for each stateid that is 2656 associated with the same index into the locking-state table. 2658 By matching the incoming stateid and its field values with the state 2659 held at the server, the server is able to easily determine if a 2660 stateid is valid for its current instantiation and state. If the 2661 stateid is not valid, the appropriate error can be supplied to the 2662 client. 2664 8.1.4. Use of the stateid 2666 All READ and WRITE operations contain a stateid. If the 2667 nfs_lockowner performs a READ or WRITE on a range of bytes within a 2668 locked range, the stateid (previously returned by the server) must be 2669 used to indicate that appropriate lock (record or share) is held. If 2670 no state is established by the client, either record lock or share 2671 lock, a stateid of all bits 0 is used. If no conflicting locks are 2672 held on the file, the server may service the READ or WRITE operation. 2673 If a conflict with an explicit lock occurs, an error is returned for 2674 the operation (NFS4ERR_LOCKED). This allows "mandatory locking" to be 2676 Draft Specification NFS version 4 Protocol February 2000 2678 implemented. 2680 A stateid of all bits 1 (one) allows READ operations to bypass record 2681 locking checks at the server. However, WRITE operations with stateid 2682 with bits all 1 (one) do not bypass record locking checks. File 2683 locking checks are handled by the OPEN operation (see the section 2684 "OPEN/CLOSE Operations"). 2686 An explicit lock may not be granted while a READ or WRITE operation 2687 with conflicting implicit locking is being performed. 2689 8.1.5. Sequencing of Lock Requests 2691 Locking is different than most NFS operations as it requires "at- 2692 most-one" semantics that are not provided by ONCRPC. In the face of 2693 retransmission or reordering, lock or unlock requests must have a 2694 well defined and consistent behavior. To accomplish this, each lock 2695 request contains a sequence number that is a consecutively increasing 2696 integer. Different nfs_lockowners have different sequences. The 2697 server maintains the last sequence number (L) received and the 2698 response that was returned. 2700 If a request with a previous sequence number (r < L) is received, it 2701 is rejected with the return of error NFS4ERR_BAD_SEQID. Given a 2702 properly-functioning client, the response to (r) must have been 2703 received before the last request (L) was sent. If a duplicate of 2704 last request (r == L) is received, the stored response is returned. 2705 If a request beyond the next sequence (r == L + 2) is received, it is 2706 rejected with the return of error NFS4ERR_BAD_SEQID. Sequence 2707 history is reinitialized whenever the client verifier changes. 2709 Since the sequence number is represented with an unsigned 32-bit 2710 integer, the arithmetic involved with the sequence number is mod 2711 2^32. 2713 It is critical the server maintain the last response sent to the 2714 client to provide a more reliable cache of duplicate non-idempotent 2715 requests than that of the traditional cache described in [Juszczak]. 2716 The traditional duplicate request cache uses a least recently used 2717 algorithm for removing unneeded requests. However, the last lock 2718 request and response on a given nfs_lockowner must be cached as long 2719 as the lock state exists on the server. 2721 8.1.6. Recovery from Replayed Requests 2723 As described above, the sequence number is per nfs_lockowner. As 2725 Draft Specification NFS version 4 Protocol February 2000 2727 long as the server maintains the last sequence number received and 2728 follows the methods described above, there are no risks of a 2729 byzantine router re-sending old requests. The server need only 2730 maintain the nfs_lockowner, sequence number state as long as there 2731 are open files or closed files with locks outstanding. 2733 LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence 2734 number and therefore the risk of the replay of these operations 2735 resulting in undesired effects is non-existent while the server 2736 maintains the nfs_lockowner state. 2738 8.1.7. Releasing nfs_lockowner State 2740 When a particular nfs_lockowner no longer holds open or file locking 2741 state at the server, the server may choose to release the sequence 2742 number state associated with the nfs_lockowner. The server may make 2743 this choice based on lease expiration, for the reclamation of server 2744 memory, or other implementation specific details. In any event, the 2745 server is able to do this safely only when the nfs_lockowner no 2746 longer is being utilized by the client. The server may choose to 2747 hold the nfs_lockowner state in the event that retransmitted requests 2748 are received. However, the period to hold this state is 2749 implementation specific. 2751 In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is 2752 retransmitted after the server has previously released the 2753 nfs_lockowner state, the server will find that the nfs_lockowner has 2754 no files open and an error will be returned to the client. If the 2755 nfs_lockowner does have a file open, the stateid will not match and 2756 again an error is returned to the client. 2758 In the case that an OPEN is retransmitted and the nfs_lockowner is 2759 being used for the first time or the nfs_lockowner state has been 2760 previously released by the server, the use of the OPEN_CONFIRM 2761 operation will prevent incorrect behavior. When the server observes 2762 the use of the nfs_lockowner for the first time, it will direct the 2763 client to perform the OPEN_CONFIRM for the corresponding OPEN. This 2764 sequence establishes the use of an nfs_lockowner and associated 2765 sequence number. See the section "OPEN_CONFIRM - Confirm Open" for 2766 further details. 2768 8.2. Lock Ranges 2770 The protocol allows a lock owner to request a lock with one byte 2771 range and then either upgrade or unlock a sub-range of the initial 2772 lock. It is expected that this will be an uncommon type of request. 2774 Draft Specification NFS version 4 Protocol February 2000 2776 In any case, servers or server file systems may not be able to 2777 support sub-range lock semantics. In the event that a server 2778 receives a locking request that represents a sub-range of current 2779 locking state for the lock owner, the server is allowed to return the 2780 error NFS4ERR_LOCK_RANGE to signify that it does not support sub- 2781 range lock operations. Therefore, the client should be prepared to 2782 receive this error and, if appropriate, report the error to the 2783 requesting application. 2785 The client is discouraged from coalescing adjacent ranges since the 2786 server may not support sub-range requests and for reasons related to 2787 the recovery of file locking state in the event of server failure. 2788 As discussed in the section "Server Failure and Recovery" below, the 2789 server may employ certain optimizations during recovery that work 2790 effectively only when the client's behavior during lock recovery is 2791 similar to the client's locking behavior prior to server failure. 2793 8.3. Blocking Locks 2795 Some clients require the support of blocking locks. The NFS version 2796 4 protocol must not rely on a callback mechanism and therefore is 2797 unable to notify a client when a previously denied lock has been 2798 granted. Clients have no choice but to continually poll for the 2799 lock. This presents a fairness problem. Two new lock types are 2800 added, READW and WRITEW, and are used to indicate to the server that 2801 the client is requesting a blocking lock. The server should maintain 2802 an ordered list of pending blocking locks. When the conflicting lock 2803 is released, the server may wait the lease period for the first 2804 waiting client to re-request the lock. After the lease period 2805 expires the next waiting client request is allowed the lock. Clients 2806 are required to poll at an interval sufficiently small that it is 2807 likely to acquire the lock in a timely manner. The server is not 2808 required to maintain a list of pending blocked locks as it is used to 2809 increase fairness and not correct operation. Because of the 2810 unordered nature of crash recovery, storing of lock state to stable 2811 storage would be required to guarantee ordered granting of blocking 2812 locks. 2814 Servers may also note the lock types and delay returning denial of 2815 the request to allow extra time for a conflicting lock to be 2816 released, allowing a successful return. In this way, clients can be 2817 avoid the burden of needlessly frequent polling for blocking locks. 2818 The server should take care in the length of delay in the event the 2819 client retransmits the request. 2821 Draft Specification NFS version 4 Protocol February 2000 2823 8.4. Lease Renewal 2825 The purpose of a lease is to allow a server to remove stale locks 2826 that are held by a client that has crashed or is otherwise 2827 unreachable. It is not a mechanism for cache consistency and lease 2828 renewals may not be denied if the lease interval has not expired. 2830 The following events cause implicit renewal of all of the leases for 2831 a given client (i.e. all those sharing a given clientid). Each of 2832 these is a positive indication that the client is still active and 2833 that the associated state held at the server, for the client, is 2834 still valid. 2836 o An OPEN with a valid clientid. 2838 o Any operation made with a valid stateid (CLOSE, DELEGRETURN, 2839 LOCK, LOCKU, OPEN, OPEN_CONFIRM, READ, RENEW, SETATTR, WRITE). 2840 This does not include the special stateids of all bits 0 or all 2841 bits 1. 2843 Note that if the client had restarted or rebooted, the 2844 client would not be making these requests without issuing 2845 the SETCLIENTID operation. The use of the SETCLIENTID 2846 operation (possibly with the addition of the optional 2847 SETCLIENTID_CONFIRM operation) notifies the server to drop 2848 the locking state associated with the client. 2850 If the server has rebooted, the stateids 2851 (NFS4ERR_STALE_STATEID error) or the clientid 2852 (NFS4ERR_STALE_CLIENTID error) will not be valid hence 2853 preventing spurious renewals. 2855 This approach allows for low overhead lease renewal which scales 2856 well. In the typical case no extra RPC calls are required for lease 2857 renewal and in the worst case one RPC is required every lease period 2858 (i.e. a RENEW operation). The number of locks held by the client is 2859 not a factor since all state for the client is involved with the 2860 lease renewal action. 2862 Since all operations that create a new lease also renew existing 2863 leases, the server must maintain a common lease expiration time for 2864 all valid leases for a given client. This lease time can then be 2865 easily updated upon implicit lease renewal actions. 2867 8.5. Crash Recovery 2869 The important requirement in crash recovery is that both the client 2871 Draft Specification NFS version 4 Protocol February 2000 2873 and the server know when the other has failed. Additionally, it is 2874 required that a client sees a consistent view of data across server 2875 restarts or reboots. All READ and WRITE operations that may have 2876 been queued within the client or network buffers must wait until the 2877 client has successfully recovered the locks protecting the READ and 2878 WRITE operations. 2880 8.5.1. Client Failure and Recovery 2882 In the event that a client fails, the server may recover the client's 2883 locks when the associated leases have expired. Conflicting locks 2884 from another client may only be granted after this lease expiration. 2885 If the client is able to restart or reinitialize within the lease 2886 period the client may be forced to wait the remainder of the lease 2887 period before obtaining new locks. 2889 To minimize client delay upon restart, lock requests are associated 2890 with an instance of the client by a client supplied verifier. This 2891 verifier is part of the initial SETCLIENTID call made by the client. 2892 The server returns a clientid as a result of the SETCLIENTID 2893 operation. The client then confirms the use of the verifier with 2894 SETCLIENTID_CONFIRM. The clientid in combination with an opaque 2895 owner field is then used by the client to identify the lock owner for 2896 OPEN. This chain of associations is then used to identify all locks 2897 for a particular client. 2899 Since the verifier will be changed by the client upon each 2900 initialization, the server can compare a new verifier to the verifier 2901 associated with currently held locks and determine that they do not 2902 match. This signifies the client's new instantiation and subsequent 2903 loss of locking state. As a result, the server is free to release 2904 all locks held which are associated with the old clientid which was 2905 derived from the old verifier. 2907 For secure environments, a change in the verifier must only cause the 2908 release of locks associated with the authenticated requester. This 2909 is required to prevent a rogue entity from freeing otherwise valid 2910 locks. 2912 Note that the verifier must have the same uniqueness properties of 2913 the verifier for the COMMIT operation. 2915 8.5.2. Server Failure and Recovery 2917 If the server loses locking state (usually as a result of a restart 2918 or reboot), it must allow clients time to discover this fact and re- 2920 Draft Specification NFS version 4 Protocol February 2000 2922 establish the lost locking state. The client must be able to re- 2923 establish the locking state without having the server deny valid 2924 requests because the server has granted conflicting access to another 2925 client. Likewise, if there is the possibility that clients have not 2926 yet re-established their locking state for a file, the server must 2927 disallow READ and WRITE operations for that file. The duration of 2928 this recovery period is equal to the duration of the lease period. 2930 A client can determine that server failure (and thus loss of locking 2931 state) has occurred, when it receives one of two errors. The 2932 NFS4ERR_STALE_STATEID error indicates a stateid invalidated by a 2933 reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a 2934 clientid invalidated by reboot or restart. When either of these are 2935 received, the client must establish a new clientid (See the section 2936 "Client ID") and re-establish the locking state as discussed below. 2938 The period of special handling of locking and READs and WRITEs, equal 2939 in duration to the lease period, is referred to as the "grace 2940 period". During the grace period, clients recover locks and the 2941 associated state by reclaim-type locking requests (i.e. LOCK requests 2942 with reclaim set to true and OPEN operations with a claim type of 2943 CLAIM_PREVIOUS). During the grace period, the server must reject 2944 READ and WRITE operations and non-reclaim locking requests (i.e. 2945 other LOCK and OPEN operations) with an error of NFS4ERR_GRACE. 2947 If the server can reliably determine that granting a non-reclaim 2948 request will not conflict with reclamation of locks by other clients, 2949 the NFS4ERR_GRACE error does not have to be returned and the non- 2950 reclaim client request can be serviced. For the server to be able to 2951 service READ and WRITE operations during the grace period, it must 2952 again be able to guarantee that no possible conflict could arise 2953 between an impending reclaim locking request and the READ or WRITE 2954 operation. If the server is unable to offer that guarantee, the 2955 NFS4ERR_GRACE error must be returned to the client. 2957 For a server to provide simple, valid handling during the grace 2958 period, the easiest method is to simply reject all non-reclaim 2959 locking requests and READ and WRITE operations by returning the 2960 NFS4ERR_GRACE error. However, a server may keep information about 2961 granted locks in stable storage. With this information, the server 2962 could determine if a regular lock or READ or WRITE operation can be 2963 safely processed. 2965 For example, if a count of locks on a given file is available in 2966 stable storage, the server can track reclaimed locks for the file and 2967 when all reclaims have been processed, non-reclaim locking requests 2968 may be processed. This way the server can ensure that non-reclaim 2969 locking requests will not conflict with potential reclaim requests. 2971 Draft Specification NFS version 4 Protocol February 2000 2973 With respect to I/O requests, if the server is able to determine that 2974 there are no outstanding reclaim requests for a file by information 2975 from stable storage or another similar mechanism, the processing of 2976 I/O requests could proceed normally for the file. 2978 To reiterate, for a server that allows non-reclaim lock and I/O 2979 requests to be processed during the grace period, it MUST determine 2980 that no lock subsequently reclaimed will be rejected and that no lock 2981 subsequently reclaimed would have prevented any I/O operation 2982 processed during the grace period. 2984 Clients should be prepared for the return of NFS4ERR_GRACE errors for 2985 non-reclaim lock and I/O requests. In this case the client should 2986 employ a backoff and retry mechanism for the request. Timeout 2987 periods should be chosen to avoid overwhelming a server. The client 2988 must account for the server that is able to perform I/O and non- 2989 reclaim locking requests within the grace period as well as those 2990 that can not do so. 2992 A reclaim-type locking request outside the server's grace period can 2993 only succeed if the server can guarantee that no conflicting lock or 2994 I/O request has been granted since reboot or restart. 2996 8.5.3. Network Partitions and Recovery 2998 If the duration of a network partition is greater than the lease 2999 period provided by the server, the server will have not received a 3000 lease renewal from the client. If this occurs, the server may free 3001 all locks held for the client. As a result, all stateids held by the 3002 client will become invalid or stale. Once the client is able to 3003 reach the server after such a network partition, all I/O submitted by 3004 the client with the now invalid stateids will fail with the server 3005 returning the error NFS4ERR_EXPIRED. Once this error is received, 3006 the client will suitably notify the application that held the lock. 3008 As a courtesy to the client or as an optimization, the server may 3009 continue to hold locks on behalf of a client for which recent 3010 communication has extended beyond the lease period. If the server 3011 receives a lock or I/O request that conflicts with one of these 3012 courtesy locks, the server must free the courtesy lock and grant the 3013 new request. 3015 In the event of a network partition with a duration extending beyond 3016 the expiration of a client's leases, the server MUST employ a method 3017 of recording this fact in its stable storage. Conflicting locks 3018 requests from another client may be serviced after the lease 3019 expiration. There are various scenarios involving server failure 3021 Draft Specification NFS version 4 Protocol February 2000 3023 after such an event that require the storage of these lease 3024 expirations or network partitions. One scenario is as follows: 3026 A client holds a lock at the server and encounters a 3027 network partition and is unable to renew the associated 3028 lease. A second client obtains a conflicting lock and then 3029 frees the lock. After the unlock request by the second 3030 client, the server reboots or reinitializes. Once the 3031 server recovers, the network partition heals and the 3032 original client attempts to reclaim the original lock. 3034 In this scenario and without any state information, the server will 3035 allow the reclaim and the client will be in an inconsistent state 3036 because the server or the client has no knowledge of the conflicting 3037 lock. 3039 The server may choose to store this lease expiration or network 3040 partitioning state in a way that will only identify the client as a 3041 whole. Note that this may potentially lead to lock reclaims being 3042 denied unnecessarily because of a mix of conflicting and non- 3043 conflicting locks. The server may also choose to store information 3044 about each lock that has an expired lease with an associated 3045 conflicting lock. The choice of the amount and type of state 3046 information that is stored is left to the implementor. In any case, 3047 the server must have enough state information to enable correct 3048 recovery from multiple partitions and multiple server failures. 3050 8.6. Recovery from a Lock Request Timeout or Abort 3052 In the event a lock request times out, a client may decide to not 3053 retry the request. The client may also abort the request when the 3054 process for which it was issued is terminated (e.g. in UNIX due to a 3055 signal. It is possible though that the server received the request 3056 and acted upon it. This would change the state on the server without 3057 the client being aware of the change. It is paramount that the 3058 client re-synchronize state with server before it attempts any other 3059 operation that takes a seqid and/or a stateid with the same 3060 nfs_lockowner. This is straightforward to do without a special re- 3061 synchronize operation. 3063 Since the server maintains the last lock request and response 3064 received on the nfs_lockowner, for each nfs_lockowner, the client 3065 should cache the last lock request it sent such that the lock request 3066 did not receive a response. From this, the next time the client does 3067 a lock operation for the nfs_lockowner, it can send the cached 3068 request, if there is one, and if the request was one that established 3070 Draft Specification NFS version 4 Protocol February 2000 3072 state (e.g. a LOCK or OPEN operation) the client can follow up with a 3073 request to remove the state (e.g. a LOCKU or CLOSE operation). With 3074 this approach, the sequencing and stateid information on the client 3075 and server for the given nfs_lockowner will re-synchronize and in 3076 turn the lock state will re-synchronize. 3078 8.7. Server Revocation of Locks 3080 At any point, the server can revoke locks held by a client and the 3081 client must be prepared for this event. When the client detects that 3082 its locks have been or may have been revoked, the client is 3083 responsible for validating the state information between itself and 3084 the server. Validating locking state for the client means that it 3085 must verify or reclaim state for each lock currently held. 3087 The first instance of lock revocation is upon server reboot or re- 3088 initialization. In this instance the client will receive an error 3089 (NFS4ERR_STALE_STATEID or NFS4ERR_STALE_CLIENTID) and the client will 3090 proceed with normal crash recovery as described in the previous 3091 section. 3093 The second lock revocation event can occur as a result of 3094 administrative intervention within the lease period. While this is 3095 considered a rare event, it is possible that the server's 3096 administrator has decided to release or revoke a particular lock held 3097 by the client. As a result of revocation, the client will receive an 3098 error of NFS4ERR_EXPIRED and the error is received within the lease 3099 period for the lock. In this instance the client may assume that 3100 only the nfs_lockowner's locks have been lost. The client notifies 3101 the lock holder appropriately. The client may not assume the lease 3102 period has been renewed as a result of failed operation. 3104 The third lock revocation event is the inability to renew the lease 3105 period. While this is considered a rare or unusual event, the client 3106 must be prepared to recover. Both the server and client will be able 3107 to detect the failure to renew the lease and are capable of 3108 recovering without data corruption. For the server, it tracks the 3109 last renewal event serviced for the client and knows when the lease 3110 will expire. Similarly, the client must track operations which will 3111 renew the lease period. Using the time that each such request was 3112 sent and the time that the corresponding reply was received, the 3113 client should bound the time that the corresponding renewal could 3114 have occurred on the server and thus determine if it is possible that 3115 a lease period expiration could have occurred. 3117 When the client determines the lease period may have expired, the 3118 client must mark all locks held for the associated lease as 3120 Draft Specification NFS version 4 Protocol February 2000 3122 "unvalidated". This means the client has been unable to re-establish 3123 or confirm the appropriate lock state with the server. As described 3124 in the previous section on crash recovery, there are scenarios in 3125 which the server may grant conflicting locks after the lease period 3126 has expired for a client. When it is possible that the lease period 3127 has expired, the client must validate each lock currently held to 3128 ensure that a conflicting lock has not been granted. The client may 3129 accomplish this task by issuing an I/O request, either a pending I/O 3130 or a zero-length read, specifying the stateid associated with the 3131 lock in question. If the response to the request is success, the 3132 client has validated all of the locks governed by that stateid and 3133 re-established the appropriate state between itself and the server. 3134 If the I/O request is not successful, then one or more of the locks 3135 associated with the stateid was revoked by the server and the client 3136 must notify the owner. 3138 8.8. Share Reservations 3140 A share reservation is a mechanism to control access to a file. It 3141 is a separate and independent mechanism from record locking. When a 3142 client opens a file, it issues an OPEN operation to the server 3143 specifying the type of access required (READ, WRITE, or BOTH) and the 3144 type of access to deny others (deny NONE, READ, WRITE, or BOTH). If 3145 the OPEN fails the client will fail the application's open request. 3147 Pseudo-code definition of the semantics: 3149 if ((request.access & file_state.deny)) || 3150 (request.deny & file_state.access)) 3151 return (NFS4ERR_DENIED) 3153 The constants used for the OPEN and OPEN_DOWNGRADE operations for the 3154 access and deny fields are as follows: 3156 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 3157 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 3158 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 3160 const OPEN4_SHARE_DENY_NONE = 0x00000000; 3161 const OPEN4_SHARE_DENY_READ = 0x00000001; 3162 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 3163 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 3165 Draft Specification NFS version 4 Protocol February 2000 3167 8.9. OPEN/CLOSE Operations 3169 To provide correct share semantics, a client MUST use the OPEN 3170 operation to obtain the initial filehandle and indicate the desired 3171 access and what if any access to deny. Even if the client intends to 3172 use a stateid of all 0's or all 1's, it must still obtain the 3173 filehandle for the regular file with the OPEN operation so the 3174 appropriate share semantics can be applied. For clients that do not 3175 have a deny mode built into their open programming interfaces, deny 3176 equal to NONE should be used. 3178 The OPEN operation with the CREATE flag, also subsumes the CREATE 3179 operation for regular files as used in previous versions of the NFS 3180 protocol. This allows a create with a share to be done atomically. 3182 The CLOSE operation removes all share locks held by the nfs_lockowner 3183 on that file. If record locks are held, the client SHOULD release 3184 all locks before issuing a CLOSE. The server MAY free all 3185 outstanding locks on CLOSE but some servers may not support the CLOSE 3186 of a file that still has record locks held. The server MUST return 3187 failure if any locks would exist after the CLOSE. 3189 The LOOKUP operation is preserved and will return a filehandle 3190 without establishing any lock state on the server. Without a valid 3191 stateid, the server will assume the client has the least access. For 3192 example, a file opened with deny READ/WRITE cannot be accessed using 3193 a filehandle obtained through LOOKUP because it would not have a 3194 valid stateid (i.e. using a stateid of all bits 0 or all bits 1). 3196 8.10. Open Upgrade and Downgrade 3198 When an OPEN is done for a file and the lockowner for which the open 3199 is being done already has the file open, the result is to upgrade the 3200 open file status maintained on the server to include the access and 3201 deny bits specified by the new OPEN as well as those for the existing 3202 OPEN. The result is that there is one open file, as far as the 3203 protocol is concerned, and it includes the union of the access and 3204 deny bits for all of the OPEN requests completed. Only a single 3205 CLOSE will be done to reset the effects of both OPEN's. Note that 3206 the client, when issuing the OPEN, may not know that the same file is 3207 in fact being opened. The above only applies if both OPEN's result 3208 in the OPEN'ed object being designated by the same filehandle. 3210 When the server chooses to export multiple filehandles corresponding 3211 to the same file object and returns different filehandles on two 3212 different OPEN's of the same file object, the server MUST NOT "OR" 3213 together the access and deny bits and coalesce the two open files. 3215 Draft Specification NFS version 4 Protocol February 2000 3217 Instead the server must maintain separate OPEN's with separate 3218 stateid's and will require separate CLOSE's to free them. 3220 When multiple open files on the client are merged into a single open 3221 file object on the server, the close of one of the open files (on the 3222 client) may necessitate change of the access and deny status of the 3223 open file on the server. This is because the union of the access and 3224 deny bits for the remaining open's may be smaller (i.e. a proper 3225 subset) than previously. The OPEN_DOWNGRADE operation is used to 3226 make the necessary change and the client should use it to update the 3227 server so that share reservation requests by other clients are 3228 handled properly. 3230 8.11. Short and Long Leases 3232 When determining the time period for the server lease, the usual 3233 lease tradeoffs apply. Short leases are good for fast server 3234 recovery at a cost of increased RENEW or READ (with zero length) 3235 requests. Longer leases are certainly kinder and gentler to large 3236 internet servers trying to handle a very large numbers of clients. 3237 The number of RENEW requests drop in proportion to the lease time. 3238 The disadvantages of long leases are slower recovery after server 3239 failure (server must wait for leases to expire and grace period 3240 before granting new lock requests) and increased file contention (if 3241 client fails to transmit an unlock request then server must wait for 3242 lease expiration before granting new locks). 3244 Long leases are usable if the server is able to store lease state in 3245 non-volatile memory. Upon recovery, the server can reconstruct the 3246 lease state from its non-volatile memory and continue operation with 3247 its clients and therefore long leases are not an issue. 3249 8.12. Clocks and Calculating Lease Expiration 3251 To avoid the need for synchronized clocks, lease times are granted by 3252 the server as a time delta. However, there is a requirement that the 3253 client and server clocks do not drift excessively over the duration 3254 of the lock. There is also the issue of propagation delay across the 3255 network which could easily be several hundred milliseconds as well as 3256 the possibility that requests will be lost and need to be 3257 retransmitted. 3259 To take propagation delay into account, the client should subtract it 3260 from lease times (e.g. if the client estimates the one-way 3261 propagation delay as 200 msec, then it can assume that the lease is 3262 already 200 msec old when it gets it). In addition, it will take 3264 Draft Specification NFS version 4 Protocol February 2000 3266 another 200 msec to get a response back to the server. So the client 3267 must send a lock renewal or write data back to the server 400 msec 3268 before the lease would expire. 3270 Draft Specification NFS version 4 Protocol February 2000 3272 9. Client-Side Caching 3274 Client-side caching of data, of file attributes, and of file names is 3275 essential to providing good performance with the NFS protocol. 3276 Providing distributed cache coherence is a difficult problem and 3277 previous versions of the NFS protocol have not attempted it. 3278 Instead, several NFS client implementation techniques have been used 3279 to reduce the problems that a lack of coherence poses for users. 3280 These techniques have not been clearly defined by earlier protocol 3281 specifications and it is often unclear what is valid or invalid 3282 client behavior. 3284 The NFS version 4 protocol uses many techniques similar to those that 3285 have been used in previous protocol versions. The NFS version 4 3286 protocol does not provide distributed cache coherence. However, it 3287 defines a more limited set of caching guarantees to allow locks and 3288 share reservations to be used without destructive interference from 3289 client side caching. 3291 In addition, the NFS version 4 protocol introduces a delegation 3292 mechanism which allows many decisions normally made by the server to 3293 be made locally by clients. This mechanism provides efficient 3294 support of the common cases where sharing is infrequent or where 3295 sharing is read-only. 3297 9.1. Performance Challenges for Client-Side Caching 3299 Caching techniques used in previous versions of the NFS protocol have 3300 been successful in providing good performance. However, several 3301 scalability challenges can arise when those techniques are used with 3302 very large numbers of clients. This is particularly true when 3303 clients are geographically distributed which classically increases 3304 the latency for cache revalidation requests. 3306 The previous versions of the NFS protocol repeat their file data 3307 cache validation requests at the time the file is opened. This 3308 behavior can have serious performance drawbacks. A common case is 3309 one in which a file is only accessed by a single client. Therefore, 3310 sharing is infrequent. 3312 In this case, repeated reference to the server to find that no 3313 conflicts exist is expensive. A better option with regards to 3314 performance is to allow a client that repeatedly opens a file to do 3315 so without reference to the server. This is done until potentially 3316 conflicting operations from another client actually occur. 3318 A similar situation arises in connection with file locking. Sending 3320 Draft Specification NFS version 4 Protocol February 2000 3322 file lock and unlock requests to the server as well as the read and 3323 write requests necessary to make data caching consistent with the 3324 locking semantics (see the section "Data Caching and File Locking") 3325 can severely limit performance. When locking is used to provide 3326 protection against infrequent conflicts, a large penalty is incurred. 3327 This penalty may discourage the use of file locking by applications. 3329 The NFS version 4 protocol provides more aggressive caching 3330 strategies with the following design goals: 3332 o Compatibility with a large range of server semantics. 3334 o Provide the same caching benefits as previous versions of the 3335 NFS protocol when unable to provide the more aggressive model. 3337 o Requirements for aggressive caching are organized so that a 3338 large portion of the benefit can be obtained even when not all 3339 of the requirements can be met. 3341 The appropriate requirements for the server are discussed in later 3342 sections in which specific forms of caching are covered. (see the 3343 section "Open Delegation"). 3345 9.2. Delegation and Callbacks 3347 Recallable delegation of server responsibilities for a file to a 3348 client improves performance by avoiding repeated requests to the 3349 server in the absence of inter-client conflict. With the use of a 3350 "callback" RPC from server to client, a server recalls delegated 3351 responsibilities when another client engages in sharing of a 3352 delegated file. 3354 A delegation is passed from the server to the client, specifying the 3355 object of the delegation and the type of delegation. There are 3356 different types of delegations but each type contains a stateid to be 3357 used to represent the delegation when performing operations that 3358 depend on the delegation. This stateid is similar to those 3359 associated with locks and share reservations but differs in that the 3360 stateid for a delegation is associated with a clientid and may be 3361 used on behalf of all the nfs_lockowners for the given client. A 3362 delegation is made to the client as a whole and not to any specific 3363 process or thread of control within it. 3365 Because callback RPCs may not work in all environments (due to 3366 firewalls, for example), correct protocol operation does not depend 3367 on them. Preliminary testing of callback functionality by means of a 3369 Draft Specification NFS version 4 Protocol February 2000 3371 CB_NULL procedure determines whether callbacks can be supported. The 3372 CB_NULL procedure checks the continuity of the callback path. A 3373 server makes a preliminary assessment of callback availability to a 3374 given client and avoids delegating responsibilities until it has 3375 determined that callbacks are supported. Because the granting of a 3376 delegation is always conditional upon the absence of conflicting 3377 access, clients must not assume that a delegation will be granted and 3378 they must always be prepared for OPENs to be processed without any 3379 delegations being granted. 3381 Once granted, a delegation behaves in most ways like a lock. There 3382 is an associated lease that is subject to renewal together with all 3383 of the other leases held by that client. 3385 Unlike locks, an operation by a second client to a delegated file 3386 will cause the server to recall a delegation through a callback. 3388 On recall, the client holding the delegation must flush modified 3389 state (such as modified data) to the server and return the 3390 delegation. The conflicting request will not receive a response 3391 until the recall is complete. The recall is considered complete when 3392 the client returns the delegation or the server times out on the 3393 recall and revokes the delegation as a result of the timeout. 3394 Following the resolution of the recall, the server has the 3395 information necessary to grant or deny the second client's request. 3397 At the time the client receives a delegation recall, it may have 3398 substantial state that needs to be flushed to the server. Therefore, 3399 the server should allow sufficient time for the recall RPC to 3400 complete since it may involve numerous RPCs to the server. If the 3401 server is able to determine that the client is diligently flushing 3402 state to the server as a result of the recall, the server may extend 3403 the usual time allowed for a recall. However, the time allowed for 3404 recall completion should not be unbounded. 3406 An example of this is when responsibility to mediate opens on a given 3407 file is delegated to a client (see the section "Open Delegation"). 3408 The server will not know what opens are in effect on the client. 3409 Without this knowledge the server will be unable to determine if the 3410 access and deny state for the file allows any particular open until 3411 the delegation for the file has been returned. 3413 A client failure or a network partition can result in failure to 3414 respond to a recall callback. In this case, the server will revoke 3415 the delegation which in turn will render useless any modified state 3416 still on the client. 3418 Draft Specification NFS version 4 Protocol February 2000 3420 9.2.1. Delegation Recovery 3422 There are three situations that delegation recovery must deal with: 3424 o Client reboot or restart 3426 o Server reboot or restart 3428 o Network partition (full or callback-only) 3430 In the event the client reboots or restarts, the failure to renew 3431 leases will result in the revocation of record locks and share 3432 reservations. Delegations, however, may treated a bit differently. 3434 There will be situations in which delegations will need to be 3435 reestablished after a client reboots or restarts. The reason for 3436 this is the client may have file data stored locally and this data 3437 was associated with the previously held delegations. The client will 3438 need to reestablish the appropriate file state on the server. 3440 To allow for this type of client recovery, the server may extend the 3441 period for delegation recovery beyond the typical lease expiration 3442 period. This implies that requests from other clients that conflict 3443 with these delegations will need to wait. This behavior is 3444 consistent with the normal recall process may take significant time 3445 because of the client's need to flush state to the server. This 3446 longer interval would increase the window for clients to reboot and 3447 consult stable storage so that the delegations can be reclaimed. For 3448 open delegations, such delegations are reclaimed using OPEN with a 3449 claim type of CLAIM_DELEGATE_PREV. (see the sections on "Data 3450 Caching and Revocation" and "Operation 18: OPEN" for discussion of 3451 open delegation and the details of OPEN respectively). 3453 When the server reboots or restarts, delegations are reclaimed (using 3454 the OPEN operation with CLAIM_DELEGATE_PREV) in a similar fashion to 3455 record locks and share reservations. However, there is a slight 3456 semantic difference. In the normal case if the server decides that a 3457 delegation should not be granted, it performs the requested action 3458 (e.g. OPEN) without granting any delegation. For reclaim, the server 3459 grants the delegation but a special designation is applied so that 3460 the client treats the delegation as having been granted but recalled 3461 by the server. Because of this, the client has the duty to write all 3462 modified state to the server and then return the delegation. This 3463 process of handling delegation reclaim reconciles three principles of 3464 the NFS Version 4 protocol: 3466 Draft Specification NFS version 4 Protocol February 2000 3468 o Upon reclaim, a client reporting resources assigned to it by an 3469 earlier server instance must be granted those resources. 3471 o The server has unquestionable authority to determine whether 3472 delegations are to be granted and, once granted, whether they 3473 are to be continued. 3475 o The use of callbacks is not to be depended upon until the client 3476 has proven its ability to receive them. 3478 When a network partition occurs, delegations are subject to freeing 3479 by the server when the lease renewal period expires. This is similar 3480 to the behavior for locks and share reservations. For delegations, 3481 however, the server may extend the period in which conflicting 3482 requests are held off. Eventually the occurrence of a conflicting 3483 request from another client will cause revocation of the delegation. 3484 A loss of the callback path (e.g. by later network configuration 3485 change) will have the same effect. A recall request will fail and 3486 revocation of the delegation will result. 3488 A client normally finds out about revocation of a delegation when it 3489 uses a stateid associated with a delegation and receives the error 3490 NFS4ERR_EXPIRED. It also may find out about delegation revocation 3491 after a client reboot when it attempts to reclaim a delegation and 3492 receives that same error. Note that in the case of a revoked write 3493 open delegation, there are issues because data may have been modified 3494 by the client whose delegation is revoked and separately by other 3495 clients. See the section "Revocation Recovery for Write Open 3496 Delegation" for a discussion of such issues. Note also that when 3497 delegations are revoked, information about the revoked delegation 3498 will be written by the server to stable storage (as described in the 3499 section "Crash Recovery"). This is done to deal with the case in 3500 which a server reboots after revoking a delegation but before the 3501 client holding the revoked delegation is notified about the 3502 revocation. 3504 9.3. Data Caching 3506 When applications share access to a set of files, they need to be 3507 implemented so as to take account of the possibility of conflicting 3508 access by another application. This is true whether the applications 3509 in question execute on different clients or reside on the same 3510 client. 3512 Share reservations and record locks are the facilities the NFS 3513 version 4 protocol provides to allow applications to coordinate 3514 access by providing mutual exclusion facilities. The NFS version 4 3516 Draft Specification NFS version 4 Protocol February 2000 3518 protocol's data caching must be implemented such that it does not 3519 invalidate the assumptions that those using these facilities depend 3520 upon. 3522 9.3.1. Data Caching and OPENs 3524 In order to avoid invalidating the sharing assumptions that 3525 applications rely on, NFS version 4 clients should not provide cached 3526 data to applications or modify it on behalf of an application when it 3527 would not be valid to obtain or modify that same data via a READ or 3528 WRITE operation. 3530 Furthermore, in the absence of open delegation (see the section "Open 3531 Delegation") two additional rules apply. Note that these rules are 3532 obeyed in practice by many NFS version 2 and version 3 clients. 3534 o First, cached data present on a client must be revalidated after 3535 doing an OPEN. This is to ensure that the data for the OPENed 3536 file is still correctly reflected in the client's cache. This 3537 validation must be done at least when the client's OPEN 3538 operation includes DENY=WRITE or BOTH thus terminating a period 3539 in which other clients may have had the opportunity to open the 3540 file with WRITE access. Clients may choose to do the 3541 revalidation more often (i.e. at OPENs specifying DENY=NONE) to 3542 parallel the NFS version 3 protocol's practice for the benefit 3543 of users assuming this degree of cache revalidation. 3545 o Second, modified data must be flushed to the server before 3546 closing a file OPENed for write. This is complementary to the 3547 first rule. If the data is not flushed at CLOSE, the 3548 revalidation done after client OPENs as file is unable to 3549 achieve its purpose. The other aspect to flushing the data 3550 before close is that the data must be committed to stable 3551 storage before the CLOSE operation is requested by the client. 3552 In the case of a server reboot or restart and a CLOSEd file, it 3553 may not be possible to retransmit the data to be written to the 3554 file. Hence, this requirement. 3556 9.3.2. Data Caching and File Locking 3558 For those applications that choose to use file locking instead of 3559 share reservations to exclude inconsistent file access, there is an 3560 analogous set of constraints that apply to client side data caching. 3561 These rules are effective only if the file locking is used in a way 3562 that matches in an equivalent way the actual READ and WRITE 3563 operations executed. This is as opposed to file locking that is 3565 Draft Specification NFS version 4 Protocol February 2000 3567 based on pure convention. For example, it is possible to manipulate 3568 a two-megabyte file by dividing the file into two one-megabyte 3569 regions and protecting access to the two regions by file locks on 3570 bytes zero and one. A lock for write on byte zero of the file would 3571 represent the right to do READ and WRITE operations on the first 3572 region. A lock for write on byte one of the file would represent the 3573 right to do READ and WRITE operations on the second region. As long 3574 as all applications manipulating the file obey this convention, they 3575 will work on a local file system. However, they may not work with 3576 the NFS version 4 protocol unless clients refrain from data caching. 3578 The rules for data caching in the file locking environment are: 3580 o First, when a client obtains a file lock for a particular 3581 region, the data cache corresponding to that region (if any 3582 cache data exists) must be revalidated. If the change attribute 3583 indicates that the file may have been updated since the cached 3584 data was obtained, the client must flush or invalidate the 3585 cached data for the newly locked region. A client might choose 3586 to invalidate all of non-modified cached data that it has for 3587 the file but the only requirement for correct operation is to 3588 invalidate all of the data in the newly locked region. 3590 o Second, before releasing a write lock for a region, all modified 3591 data for that region must be flushed to the server. The 3592 modified data must also be written to stable storage. 3594 Note that flushing data to the server and the invalidation of cached 3595 data must reflect the actual byte ranges locked or unlocked. 3596 Rounding these up or down to reflect client cache block boundaries 3597 will cause problems if not carefully done. For example, writing a 3598 modified block when only half of that block is within an area being 3599 unlocked may cause invalid modification to the region outside the 3600 unlocked area. This, in turn, may be part of a region locked by 3601 another client. Clients can avoid this situation by synchronously 3602 performing portions of write operations that overlap that portion 3603 (initial or final) that is not a full block. Similarly, invalidating 3604 a locked area which is not an integral number of full buffer blocks 3605 would require the client to read one or two partial blocks from the 3606 server if the revalidation procedure shows that the data which the 3607 client possesses may not be valid. 3609 The data that is written to the server as a pre-requisite to the 3610 unlocking of a region must be written to stable storage. The client 3611 may accomplish this either with synchronous writes or by following 3612 asynchronous writes with a COMMIT operation. This is required 3613 because retransmission of the modified data after a server reboot 3614 might conflict with a lock held by another client. 3616 Draft Specification NFS version 4 Protocol February 2000 3618 A client implementation may choose to accommodate applications which 3619 use record locking in non-standard ways (e.g. using a record lock as 3620 a global semaphore) by flushing to the server more data upon an LOCKU 3621 than is covered by the locked range. This may include modified data 3622 within files other than the one for which the unlocks are being done. 3623 In such cases, the client must not interfere with applications whose 3624 READs and WRITEs are being done only within the bounds of record 3625 locks which the application holds. For example, an application locks 3626 a single byte of a file and proceeds to write that single byte. A 3627 client that chose to handle a LOCKU by flushing all modified data to 3628 the server could validly write that single byte in response to an 3629 unrelated unlock. However, it would not be valid to write the entire 3630 block in which that single written byte was located since it includes 3631 an area that is not locked and might be locked by another client. 3632 Client implementations can avoid this problem by dividing files with 3633 modified data into those for which all modifications are done to 3634 areas covered by an appropriate record lock and those for which there 3635 are modifications not covered by a record lock. Any writes done for 3636 the former class of files must not include areas not locked and thus 3637 not modified on the client. 3639 9.3.3. Data Caching and Mandatory File Locking 3641 Client side data caching needs to respect mandatory file locking when 3642 it is in effect. The presence of mandatory file locking for a given 3643 file is indicated in the result flags for an OPEN. When mandatory 3644 locking is in effect for a file, the client must check for an 3645 appropriate file lock for data being read or written. If a lock 3646 exists for the range being read or written, the client may satisfy 3647 the request using the client's validated cache. If an appropriate 3648 file lock is not held for the range of the read or write, the read or 3649 write request must not be satisfied by the client's cache and the 3650 request sent to the server for processing. When a read or write 3651 request partially overlaps a locked region, the request should be 3652 subdivided into multiple pieces with each region (locked or not) 3653 treated appropriately. 3655 9.3.4. Data Caching and File Identity 3657 When clients cache data, the file data needs to organized according 3658 to the file system object to which the data belongs. For NFS version 3659 3 clients, the typical practice has been to assume for the purpose of 3660 caching that distinct filehandles represent distinct file system 3661 objects. The client then has the choice to organize and maintain the 3662 data cache on this basis. 3664 Draft Specification NFS version 4 Protocol February 2000 3666 In the NFS version 4 protocol, there is now the possibility to have 3667 significant deviations from a "one filehandle per object" model 3668 because a filehandle may be constructed on the basis of the object's 3669 pathname. Therefore, clients need a reliable method to determine if 3670 two filehandles designate the same file system object. If clients 3671 were simply to assume that all distinct filehandles denote distinct 3672 objects and proceed to do data caching on this basis, caching 3673 inconsistencies would arise between the distinct client side objects 3674 which mapped to the same server side object. 3676 By providing a method to differentiate filehandles, the NFS version 4 3677 protocol alleviates a potential functional regression in comparison 3678 with the NFS version 3 protocol. Without this method, caching 3679 inconsistencies within the same client could occur and this has not 3680 been present in previous versions of the NFS protocol. Note that it 3681 is possible to have such inconsistencies with applications executing 3682 on multiple clients but that is not the issue being addressed here. 3684 For the purposes of data caching, the following steps allow an NFS 3685 version 4 client to determine whether two distinct filehandles denote 3686 the same server side object: 3688 o If GETATTR directed to two filehandles have different values of 3689 the fsid attribute, then the filehandles represent distinct 3690 objects. 3692 o If GETATTR for any file with an fsid that matches the fsid of 3693 the two filehandles in question returns a unique_handles 3694 attribute with a value of TRUE, then the two objects are 3695 distinct. 3697 o If GETATTR directed to the two filehandles does not return the 3698 fileid attribute for one or both of the handles, then the it 3699 cannot be determined whether the two objects are the same. 3700 Therefore, operations which depend on that knowledge (e.g. 3701 client side data caching) cannot be done reliably. 3703 o If GETATTR directed to the two filehandles returns different 3704 values for the fileid attribute, then they are distinct objects. 3706 o Otherwise they are the same object. 3708 9.4. Open Delegation 3710 When a file is being OPENed, the server may delegate further handling 3711 of opens and closes for that file to the opening client. Any such 3713 Draft Specification NFS version 4 Protocol February 2000 3715 delegation is recallable, since the circumstances that allowed for 3716 the delegation are subject to change. In particular, the server may 3717 receive a conflicting OPEN from another client, the server must 3718 recall the delegation before deciding whether the OPEN from the other 3719 client may be granted. Making a delegation is up to the server and 3720 clients should not assume that any particular OPEN either will or 3721 will not result in an open delegation. The following is a typical 3722 set of conditions that servers might use in deciding whether OPEN 3723 should be delegated: 3725 o The client must be able to respond to the server's callback 3726 requests. The server will use the CB_NULL procedure for a test 3727 of callback ability. 3729 o The client must have responded properly to previous recalls. 3731 o There must be no current open conflicting with the requested 3732 delegation. 3734 o There should be no current delegation that conflicts with the 3735 delegation being requested. 3737 o The probability of future conflicting open requests should be 3738 low based on the recent history of the file. 3740 o The existence of any server-specific semantics of OPEN/CLOSE 3741 that would make the required handling incompatible with the 3742 prescribed handling that the delegated client would apply (see 3743 below). 3745 There are two types of open delegations, read and write. A read open 3746 delegation allows a client to handle, on its own, requests to open a 3747 file for reading that do not deny read access to others. Multiple 3748 read open delegations may be outstanding simultaneously and do not 3749 conflict. A write open delegation allows the client to handle, on 3750 its own, all opens. Only one write open delegation may exist for a 3751 given file at a given time and it is inconsistent with any read open 3752 delegations. 3754 When a client has a read open delegation, it may not make any changes 3755 to the contents or attributes of the file but it is assured that no 3756 other client may do so. When a client has a write open delegation, 3757 it may modify the file data since no other client will be accessing 3758 the file's data. The client holding a write delegation may only 3759 affect file attributes which are intimately connected with the file 3760 data: object_size, time_modify, change. 3762 When a client has an open delegation, it does not send OPENs or 3764 Draft Specification NFS version 4 Protocol February 2000 3766 CLOSEs to the server but updates the appropriate status internally. 3767 For a read open delegation, opens that cannot be handled locally 3768 (opens for write or that deny read access) must be sent to the 3769 server. 3771 When an open delegation is made, the response to the OPEN contains an 3772 open delegation structure which specifies the following: 3774 o the type of delegation (read or write) 3776 o space limitation information to control flushing of data on 3777 close (write open delegation only, see the section "Open 3778 Delegation and Data Caching") 3780 o an nfsace4 specifying read and write permissions 3782 o a stateid to represent the delegation for READ and WRITE 3784 The stateid is separate and distinct from the stateid for the OPEN 3785 proper. The standard stateid, unlike the delegation stateid, is 3786 associated with a particular nfs_lockowner and will continue to be 3787 valid after the delegation is recalled and the file remains open. 3789 When a request internal to the client is made to open a file and open 3790 delegation is in effect, it will be accepted or rejected solely on 3791 the basis of the following conditions. Any requirement for other 3792 checks to be made by the delegate should result in open delegation 3793 being denied so that the checks can be made by the server itself. 3795 o The access and deny bits for the request and the file as 3796 described in the section "Share Reservations". 3798 o The read and write permissions as determined below. 3800 The nfsace4 passed with delegation can be used to avoid frequent 3801 ACCESS calls. The permission check should be as follows: 3803 o If the nfsace4 indicates that the open may be done, then it 3804 should be granted without reference to the server. 3806 o If the nfsace4 indicates that the open may not be done, then an 3807 ACCESS request must be sent to the server to obtain the 3808 definitive answer. 3810 The server may return an nfsace4 that is more restrictive than the 3811 actual ACL of the file. This includes an nfsace4 that specifies 3812 denial of all access. Note that some common practices such as 3814 Draft Specification NFS version 4 Protocol February 2000 3816 mapping the traditional user "root" to the user "nobody" may make it 3817 incorrect to return the actual ACL of the file in the delegation 3818 response. 3820 The use of delegation together with various other forms of caching 3821 creates the possibility that no server authentication will ever be 3822 performed for a given user since all of the user's requests might be 3823 satisfied locally. Where the client is depending on the server for 3824 authentication, the client should be sure authentication occurs for 3825 each user by use of the ACCESS operation. This should be the case 3826 even if an ACCESS operation would not be required otherwise. As 3827 mentioned before, the server may enforce frequent authentication by 3828 returning an nfsace4 denying all access with every open delegation. 3830 9.4.1. Open Delegation and Data Caching 3832 OPEN delegation allows much of the message overhead associated with 3833 the opening and closing files to be eliminated. An open when an open 3834 delegation is in effect does not require that a validation message be 3835 sent to the server. The continued endurance of the "read open 3836 delegation" provides a guarantee that no OPEN for write and thus no 3837 write has occurred. Similarly, when closing a file opened for write 3838 and if write open delegation is in effect, the data written does not 3839 have to be flushed to the server until the open delegation is 3840 recalled. The continued endurance of the open delegation provides a 3841 guarantee that no open and thus no read or write has been done by 3842 another client. 3844 For the purposes of open delegation, READs and WRITEs done without an 3845 OPEN are treated as the functional equivalents of a corresponding 3846 type of OPEN. This refers to the READs and WRITEs that use the 3847 special stateids consisting of all zero bits or all one bits. 3848 Therefore, READs or WRITEs with a special stateid done by another 3849 client will force the server to recall a write open delegation. A 3850 WRITE with a special stateid done by another client will force a 3851 recall of read open delegations. 3853 With delegations, a client is able to avoid writing data to the 3854 server when the CLOSE of a file is serviced. The CLOSE operation is 3855 the usual point at which the client is notified of a lack of stable 3856 storage for the modified file data generated by the application. At 3857 the CLOSE, file data is written to the server and through normal 3858 accounting the server is able to determine if the available file 3859 system space for the data has been exceeded (i.e. server returns 3860 NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. 3861 The introduction of delegations requires that a alternative method be 3862 in place for the same type of communication to occur between client 3864 Draft Specification NFS version 4 Protocol February 2000 3866 and server. 3868 In the delegation response, the server provides either the limit of 3869 the size of the file or the number of modified blocks and associated 3870 block size. The server must ensure that the client will be able to 3871 flush data to the server of a size equal to that provided in the 3872 original delegation. The server must make this assurance for all 3873 outstanding delegations. Therefore, the server must be careful in 3874 its management of available space for new or modified data taking 3875 into account available file system space and any applicable quotas. 3876 The server can recall delegations as a result of managing the 3877 available file system space. The client should abide by the server's 3878 state space limits for delegations. If the client exceeds the stated 3879 limits for the delegation, the server's behavior is undefined. 3881 Based on server conditions, quotas or available file system space, 3882 the server may grant write open delegations with very restrictive 3883 space limitations. The limitations may be defined in a way that will 3884 always force modified data to be flushed to the server on close. 3886 With respect to authentication, flushing modified data to the server 3887 after a CLOSE has occurred may be problematic. For example, the user 3888 of the application may have logged off of the client and unexpired 3889 authentication credentials may not be present. In this case, the 3890 client may need to take special care to ensure that local unexpired 3891 credentials will in fact be available. This may be accomplished by 3892 tracking the expiration time of credentials and flushing data well in 3893 advance of their expiration or by making private copies of 3894 credentials to assure their availability when needed. 3896 9.4.2. Open Delegation and File Locks 3898 When a client holds a write open delegation, lock operations are 3899 performed locally. This includes those required for mandatory file 3900 locking. This can be done since the delegation implies that there 3901 can be no conflicting locks. Similarly, all of the revalidations 3902 that would normally be associated with obtaining locks and the 3903 flushing of data associated with the releasing of locks need not be 3904 done. 3906 9.4.3. Recall of Open Delegation 3908 The following events necessitate recall of an open delegation: 3910 o Potentially conflicting OPEN request (or READ/WRITE done with 3911 "special" stateid) 3913 Draft Specification NFS version 4 Protocol February 2000 3915 o SETATTR issued by another client 3917 o REMOVE request for the file 3919 o RENAME request for the file as either source or target of the 3920 RENAME 3922 Whether a RENAME of a directory in the path leading to the file 3923 results in recall of an open delegation depends on the semantics of 3924 the server file system. If that file system denies such RENAMEs when 3925 a file is open, the recall must be performed to determine whether the 3926 file in question is, in fact, open. 3928 In addition to the situations above, the server may choose to recall 3929 open delegations at any time if resource constraints make it 3930 advisable to do so. Clients should always be prepared for the 3931 possibility of recall. 3933 The server needs to employ special handling for a GETATTR where the 3934 target is a file that has a write open delegation in effect. In this 3935 case, the client holding the delegation needs to be interrogated. 3936 The server will use a CB_GETATTR callback, if the GETATTR attribute 3937 bits include any of the attributes that a write open delegate may 3938 modify (object_size, time_modify, change). 3940 When a client receives a recall for an open delegation, it needs to 3941 update state on the server before returning the delegation. These 3942 same updates must be done whenever a client chooses to return a 3943 delegation voluntarily. The following items of state need to be 3944 dealt with: 3946 o If the file associated with the delegation is no longer open and 3947 no previous CLOSE operation has been sent to the server, a CLOSE 3948 operation must be sent to the server. 3950 o If file has other open references at the client, then OPEN 3951 operations must be sent to the server. The appropriate stateids 3952 will be provided by the server for subsequent use by the client 3953 since the delegation stateid will not longer be valid. These 3954 OPEN requests are done with the claim type of 3955 CLAIM_DELEGATE_CUR. This will allow the presentation of the 3956 delegation stateid so that the client can establish the 3957 appropriate rights to perform the OPEN. (see the section 3958 "Operation 18: OPEN" for details.) 3960 o If there are granted file locks, the corresponding LOCK 3961 operations need to be performed. This applies to the write open 3962 delegation case only. 3964 Draft Specification NFS version 4 Protocol February 2000 3966 o For a write open delegation, if, at the time of recall, if the 3967 file is not open for write, all modified data for the file must 3968 be flushed to the server. If the delegation had not existed, 3969 the client would have done this data flush before the CLOSE 3970 operation. 3972 o With the write open delegation in place, it is possible that the 3973 file was truncated during the duration of the delegation. For 3974 example, the truncation could have occurred as a result of an 3975 OPEN UNCHECKED with a object_size attribute value of zero. 3976 Therefore, if a truncation of the file has occurred and this 3977 operation has not been propagated to the server, the truncation 3978 must occur before any modified data is written to the server. 3980 o Any modified data for the file needs to be flushed to the the 3981 server. 3983 In the case of write open delegation, file locking imposes some 3984 additional requirements. The flushing of any modified data in any 3985 region for which a write lock was released while the write open 3986 delegation was in effect is what is required to precisely maintain 3987 the associated invariant. However, because the write open delegation 3988 implies no other locking by other clients, a simpler implementation 3989 is to flush all modified data for the file (as described just above) 3990 if any write lock has been released while the write open delegation 3991 was in effect. 3993 9.4.4. Delegation Revocation 3995 At the point a delegation is revoked, if there are associated opens 3996 on the client, the applications holding these opens need to be 3997 notified. This notification usually occurs by returning errors for 3998 READ/WRITE operations or when a close is attempted for the open file. 4000 If no opens exist for the file at the point the delegation is 4001 revoked, then notification of the revocation is unnecessary. 4002 However, if there is modified data present at the client for the 4003 file, the user of the application should be notified. Unfortunately, 4004 it may not be possible to notify the user since active applications 4005 may not be present at the client. See the section "Revocation 4006 Recovery for Write Open Delegation" for additional details. 4008 9.5. Data Caching and Revocation 4010 When locks and delegations are revoked, the assumptions upon which 4011 successful caching depend are no longer guaranteed. The owner of the 4013 Draft Specification NFS version 4 Protocol February 2000 4015 locks or share reservations which have been revoked needs to be 4016 notified. This notification includes applications with a file open 4017 that has a corresponding delegation which has been revoked. Cached 4018 data associated with the revocation must be removed from the client. 4019 In the case of modified data existing in the client's cache, that 4020 data must be removed from the client without it being written to the 4021 server. 4023 Notification to a lock owner will in many cases consist of simply 4024 returning an error on the next and all subsequent READs/WRITEs to the 4025 open file or on the close. Where the methods available to a client 4026 to make such notification impossible because errors for certain 4027 operations may not be returned, more drastic action such as signals 4028 or process termination may be appropriate. The justification for 4029 this is that an invariant for which an application depends on may be 4030 violated. Depending on how errors are typically treated for the 4031 client operating environment, further levels of notification 4032 including logging, console messages, and GUI pop-ups may be 4033 appropriate. 4035 9.5.1. Revocation Recovery for Write Open Delegation 4037 Revocation recovery for a write open delegation poses the special 4038 issue of modified data in the client cache while the file is not 4039 open. In this situation, any client which does not flush modified 4040 data to the server on each close must ensure that the user receives 4041 appropriate notification of the failure as a result of the 4042 revocation. Since such situations may require human action to 4043 correct problems, notification schemes in which the appropriate user 4044 or administrator is notified may be necessary. Logging and console 4045 messages are typical examples. 4047 If there is modified data on the client, it must not be flushed 4048 normally to the server. A client may attempt to provide a copy of 4049 the file data as modified during the delegation under a different 4050 name in the file system name space to ease recovery. Unless the 4051 client can determine that the file has not modified by any other 4052 client, this technique must be limited to situations in which a 4053 client has a complete cached copy of the file in question. Use of 4054 such a technique may be limited to files under a certain size or may 4055 only be used when sufficient disk space is guaranteed to be available 4056 within the target file system and when the client has sufficient 4057 buffering resources to keep the cached copy available until it is 4058 properly stored to the target file system. 4060 Draft Specification NFS version 4 Protocol February 2000 4062 9.6. Attribute Caching 4064 The attributes discussed in this section do not include named 4065 attributes. Individual named attributes are analogous to files and 4066 caching of the data for these needs to be handled just as data 4067 caching is for ordinary files. Similarly, LOOKUP results from an 4068 OPENATTR directory are to be cached on the same basis as any other 4069 pathnames and similarly for directory contents. 4071 Clients may cache file attributes obtained from the server and use 4072 them to avoid subsequent GETATTR requests. Such caching is write 4073 through in that modification to file attributes is always done by 4074 means of requests to the server and should not be done locally and 4075 cached. The exception to this are modifications to attributes that 4076 are intimately connected with data caching. Therefore, extending a 4077 file by writing data to the local data cache is reflected immediately 4078 in the object_size as seen on the client without this change being 4079 immediately reflected on the server. Normally such changes are not 4080 propagated directly to the server but when the modified data is 4081 flushed to the server, analogous attribute changes are made on the 4082 server. When open delegation is in effect, the modified attributes 4083 may be returned to the server in the response to a CB_RECALL call. 4085 The result of local caching of attributes is that the attribute 4086 caches maintained on individual clients will not be coherent. Changes 4087 made in one order on the server may be seen in a different order on 4088 one client and in a third order on a different client. 4090 The typical file system application programming interfaces do not 4091 provide means to atomically modify or interrogate attributes for 4092 multiple files at the same time. The following rules provide an 4093 environment where the potential incoherences mentioned above can be 4094 reasonably managed. These rules are derived from the practice of 4095 previous NFS protocols. 4097 o All attributes for a given file (per-fsid attributes excepted) 4098 are cached as a unit at the client so that no non- 4099 serializability can arise within the context of a single file. 4101 o An upper time boundary is maintained on how long a client cache 4102 entry can be kept without being refreshed from the server. 4104 o When operations are performed that change attributes at the 4105 server, the updated attribute set is requested as part of the 4106 containing RPC. This includes directory operations that update 4107 attributes indirectly. This is accomplished by following the 4108 modifying operation with a GETATTR operation and then using the 4109 results of the GETATTR to update the client's cached attributes. 4111 Draft Specification NFS version 4 Protocol February 2000 4113 Note that if the full set of attributes to be cached is requested by 4114 READDIR, the results can be cached by the client on the same basis as 4115 attributes obtained via GETATTR. 4117 A client may validate its cached version of attributes for a file by 4118 fetching only the change attribute and assuming that if the change 4119 attribute has the same value as it did when the attributes were 4120 cached, then no attributes have changed. The possible exception is 4121 the attribute time_access. 4123 9.7. Name Caching 4125 The results of LOOKUP and READDIR operations may be cached to avoid 4126 the cost of subsequent LOOKUP operations. Just as in the case of 4127 attribute caching, inconsistencies may arise among the various client 4128 caches. To mitigate the effects of these inconsistencies and given 4129 the context of typical file system APIs, the following rules should 4130 be followed: 4132 o The results of unsuccessful LOOKUPs should not be cached, unless 4133 they are specifically reverified at the point of use. 4135 o An upper time boundary is maintained on how long a client name 4136 cache entry can be kept without verifying that the entry has not 4137 been made invalid by a directory change operation performed by 4138 another client. 4140 When a client is not making changes to a directory for which there 4141 exist name cache entries, the client needs to periodically fetch 4142 attributes for that directory to ensure that it is not being 4143 modified. After determining that no modification has occurred, the 4144 expiration time for the associated name cache entries may be updated 4145 to be the current time plus the name cache staleness bound. 4147 When a client is making changes to a given directory, it needs to 4148 determine whether there have been changes made to the directory by 4149 other clients. It does this by using the change attribute as 4150 reported before and after the directory operation in the associated 4151 change_info4 value returned for the operation. The server is able to 4152 communicate to the client whether the change_info4 data is provided 4153 atomically with respect to the directory operation. If the change 4154 values are provided atomically, the client is then able to compare 4155 the pre-operation change value with the change value in the client's 4156 name cache. If the comparison indicates that the directory was 4157 updated by another client, the name cache associated with the 4158 modified directory is purged from the client. If the comparison 4159 indicates no modification, the name cache can be updated on the 4161 Draft Specification NFS version 4 Protocol February 2000 4163 client to reflect the directory operation and the associated timeout 4164 extended. The post-operation change value needs to be saved as the 4165 basis for future change_info4 comparisons. 4167 As demonstrated by the scenario above, name caching requires that the 4168 client revalidate name cache data by inspecting the change attribute 4169 of a directory at the point when the name cache item was cached. 4170 This requires that the server update the change attribute for 4171 directories when the contents of the corresponding directory is 4172 modified. For a client to use the change_info4 information 4173 appropriately and correctly, the server must report the pre and post 4174 operation change attribute values atomically. When the server is 4175 unable to report the before and after values atomically with respect 4176 to the directory operation, the server must indicate that fact in the 4177 change_info4 return value. When the information is not atomically 4178 reported, the client should not assume that other clients have not 4179 changed the directory. 4181 9.8. Directory Caching 4183 The results of READDIR operations may be used to avoid subsequent 4184 READDIR operations. Just as in the cases of attribute and name 4185 caching inconsistencies may arise among the various client caches. 4186 To mitigate the effects of these inconsistencies and given the 4187 context of typical file system APIs, the following rules should be 4188 followed: 4190 o Cached READDIR information for a directory which is not obtained 4191 in a single READDIR operation must always be a consistent 4192 snapshot of directory contents. This is determined by using a 4193 GETATTR before the first READDIR and after the last of READDIR 4194 that contributes to the cache. 4196 o An upper time boundary is maintained to indicate the length of 4197 time a directory cache entry is considered valid before the 4198 client must revalidate the cached information. 4200 The revalidation technique parallels that discussed in the case of 4201 name caching. When the client is not changing the directory in 4202 question, checking the change attribute of the directory with GETATTR 4203 is adequate. The lifetime of the cache entry can be extended at 4204 these checkpoints. When a client is modifying the directory, the 4205 client needs to use the change_info4 data to determine whether there 4206 are other clients modifying the directory. If it is determined that 4207 no other client modifications are occurring, the client may update 4208 its directory cache to reflect its own changes. 4210 Draft Specification NFS version 4 Protocol February 2000 4212 As demonstrated previously, directory caching requires that the 4213 client revalidate directory cache data by inspecting the change 4214 attribute of a directory at the point when the directory was cached. 4215 This requires that the server update the change attribute for 4216 directories when the contents of the corresponding directory is 4217 modified. For a client to use the change_info4 information 4218 appropriately and correctly, the server must report the pre and post 4219 operation change attribute values atomically. When the server is 4220 unable to report the before and after values atomically with respect 4221 to the directory operation, the server must indicate that fact in the 4222 change_info4 return value. When the information is not atomically 4223 reported, the client should not assume that other clients have not 4224 changed the directory. 4226 Draft Specification NFS version 4 Protocol February 2000 4228 10. Minor Versioning 4230 To address the requirement of an NFS protocol that can evolve as the 4231 need arises, the NFS version 4 protocol contains the rules and 4232 framework to allow for future minor changes or versioning. 4234 The base assumption with respect to minor versioning is that any 4235 future accepted minor version must follow the IETF process and be 4236 documented in a standards track RFC. Therefore, each minor version 4237 number will correspond to an RFC. Minor version zero of the NFS 4238 version 4 protocol is represented by this RFC. The COMPOUND 4239 procedure will support the encoding of the minor version being 4240 requested by the client. 4242 The following items represent the basic rules for the development of 4243 minor versions. Note that a future minor version may decide to 4244 modify or add to the following rules as part of the minor version 4245 definition. 4247 1 Procedures are not added or deleted 4249 To maintain the general RPC model, NFS version 4 minor versions 4250 will not add or delete procedures from the NFS program. 4252 2 Minor versions may add operations to the COMPOUND and 4253 CB_COMPOUND procedures. 4255 The addition of operations to the COMPOUND and CB_COMPOUND 4256 procedures does not affect the RPC model. 4258 2.1 Minor versions may append attributes to GETATTR4args, bitmap4, 4259 and GETATTR4res. 4261 This allows for the expansion of the attribute model to allow 4262 for future growth or adaptation. 4264 2.2 Minor version X must append any new attributes after the last 4265 documented attribute. 4267 Since attribute results are specified as an opaque array of 4268 per-attribute XDR encoded results, the complexity of adding new 4269 attributes in the midst of the current definitions will be too 4270 burdensome. 4272 Draft Specification NFS version 4 Protocol February 2000 4274 3 Minor versions must not modify the structure of an existing 4275 operation's arguments or results. 4277 Again the complexity of handling multiple structure definitions 4278 for a single operation is too burdensome. New operations should 4279 be added instead of modifying existing structures for a minor 4280 version. 4282 This rule does not preclude the following adaptations in a minor 4283 version. 4285 o adding bits to flag fields such as new attributes to 4286 GETATTR's bitmap4 data type 4288 o adding bits to existing attributes like ACLs that have flag 4289 words 4291 o extending enumerated types (including NFS4ERR_*) with new 4292 values 4294 4 Minor versions may not modify the structure of existing 4295 attributes. 4297 5 Minor versions may not delete operations. 4299 This prevents the potential reuse of a particular operation 4300 "slot" in a future minor version. 4302 6 Minor versions may not delete attributes. 4304 7 Minor versions may not delete flag bits or enumeration values. 4306 8 Minor versions may declare an operation as mandatory to NOT 4307 implement. 4309 Specifying an operation as "mandatory to not implement" is 4310 equivalent to obsoleting an operation. For the client, it means 4311 that the operation should not be sent to the server. For the 4312 server, an NFS error can be returned as opposed to "dropping" 4313 the request as an XDR decode error. This approach allows for 4314 the obsolescence of an operation while maintaining its structure 4315 so that a future minor version can reintroduce the operation. 4317 Draft Specification NFS version 4 Protocol February 2000 4319 8.1 Minor versions may declare attributes mandatory to NOT 4320 implement. 4322 8.2 Minor versions may declare flag bits or enumeration values as 4323 mandatory to NOT implement. 4325 9 Minor versions may downgrade features from mandatory to 4326 recommended, or recommended to optional. 4328 10 Minor versions may upgrade features from optional to recommended 4329 or recommended to mandatory. 4331 11 A client and server that support minor version X must support 4332 minor versions 0 (zero) through X-1 as well. 4334 12 No new features may be introduced as mandatory in a minor 4335 version. 4337 This rule allows for the introduction of new functionality and 4338 forces the use of implementation experience before designating a 4339 feature as mandatory. 4341 13 A client MUST NOT attempt to use a stateid, file handle, or 4342 similar returned object from the COMPOUND procedure with minor 4343 version X for another COMPOUND procedure with minor version Y, 4344 where X != Y. 4346 Draft Specification NFS version 4 Protocol February 2000 4348 11. Internationalization 4350 The primary issue in which NFS needs to deal with 4351 internationalization, or i18n, is with respect to file names and 4352 other strings as used within the protocol. NFS' choice of string 4353 representation must allow reasonable name/string access to clients 4354 which use various languages. The UTF-8 encoding of the UCS as 4355 defined by [ISO10646] allows for this type of access and follows the 4356 policy described in "IETF Policy on Character Sets and Languages", 4357 [RFC2277]. This choice is explained further in the following. 4359 11.1. Universal Versus Local Character Sets 4361 [RFC1345] describes a table of 16 bit characters for many different 4362 languages (the bit encodings match Unicode, though of course RFC1345 4363 is somewhat out of date with respect to current Unicode assignments). 4364 Each character from each language has a unique 16 bit value in the 16 4365 bit character set. Thus this table can be thought of as a universal 4366 character set. [RFC1345] then talks about groupings of subsets of 4367 the entire 16 bit character set into "Charset Tables". For example 4368 one might take all the Greek characters from the 16 bit table (which 4369 are are consecutively allocated), and normalize their offsets to a 4370 table that fits in 7 bits. Thus it is determined that "lower case 4371 alpha" is in the same position as "upper case a" in the US-ASCII 4372 table, and "upper case alpha" is in the same position as "lower case 4373 a" in the US-ASCII table. 4375 These normalized subset character sets can be thought of as "local 4376 character sets", suitable for an operating system locale. 4378 Local character sets are not suitable for the NFS protocol. Consider 4379 someone who creates a file with a name in a Swedish character set. 4380 If someone else later goes to access the file with their locale set 4381 to the Swedish language, then there are no problems. But if someone 4382 in say the US-ASCII locale goes to access the file, the file name 4383 will look very different, because the Swedish characters in the 7 bit 4384 table will now be represented in US-ASCII characters on the display. 4385 It would be preferable to give the US-ASCII user a way to display the 4386 file name using Swedish glyphs. In order to do that, the NFS protocol 4387 would have to include the locale with the file name on each operation 4388 to create a file. 4390 But then what of the situation when there is a path name on the 4391 server like: 4393 /component-1/component-2/component-3 4395 Each component could have been created with a different locale. If 4397 Draft Specification NFS version 4 Protocol February 2000 4399 one issues CREATE with multi-component path name, and if some of the 4400 leading components already exist, what is to be done with the 4401 existing components? Is the current locale attribute replaced with 4402 the user's current one? These types of situations quickly become too 4403 complex when there is an alternate solution. 4405 If the NFS version 4 protocol used a universal 16 bit or 32 bit 4406 character set (or a encoding of a 16 bit or 32 bit character set into 4407 octets), then the server and client need not care if the locale of 4408 the user accessing the file is different than the locale of the user 4409 who created the file. The unique 16 bit or 32 bit encoding of the 4410 character allows for determination of what language the character is 4411 from and also how to display that character on the client. The 4412 server need not know what locales are used. 4414 11.2. Overview of Universal Character Set Standards 4416 The previous section makes a case for using a universal character 4417 set. This section makes the case for using UTF-8 as the specific 4418 universal character set for the NFS version 4 protocol. 4420 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 4421 Unicode, and UCS-*. There are two standards bodies managing 4422 universal code sets: 4424 o ISO/IEC which has the standard 10646-1 4426 o Unicode which has the Unicode standard 4428 Both standards bodies have pledged to track each other's assignments 4429 of character codes. 4431 The following is a brief analysis of the various standards. 4433 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 4434 multi-octet character set called the Universal Character 4435 Set (UCS), which encompasses most of the world's writing 4436 systems." 4438 UCS-2 a two octet per character encoding that addresses the first 4439 2^16 characters of UCS. Currently there are no UCS 4440 characters beyond that range. 4442 UCS-4 a four octet per character encoding that permits the 4443 encoding of up to 2^31 characters. 4445 Draft Specification NFS version 4 Protocol February 2000 4447 UTF UCS transformation format. 4449 UTF-1 Only historical interest; it has been removed from 10646-1 4451 UTF-7 Encodes the entire "repertoire" of UCS "characters using 4452 only octets with the higher order bit clear". [RFC2152] 4453 describes UTF-7. UTF-7 accomplishes this by reserving one 4454 of the 7bit US-ASCII characters as a "shift" character to 4455 indicate non-US-ASCII characters. 4457 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 4458 characters are encoded as before unchanged. Any octet with 4459 the high bit cleared can only mean a US-ASCII character. 4460 The high bit set means that a UCS character is being 4461 encoded. 4463 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 4464 reserved range in UCS-2. 4466 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 4468 Up to the present time, changes in Unicode and amendments 4469 to ISO/IEC 10646 have tracked each other, so that the 4470 character repertoires and code point assignments have 4471 remained in sync. The relevant standardization committees 4472 have committed to maintain this very useful synchronism. 4474 11.3. Difficulties with UCS-4, UCS-2, Unicode 4476 Adapting existing applications, and file systems to multi-octet 4477 schemes like UCS and Unicode can be difficult. A significant amount 4478 of code has been written to process streams of bytes. Also there are 4479 many existing stored objects described with 7 bit or 8 bit 4480 characters. Doubling or quadrupling the bandwidth and storage 4481 requirements seems like an expensive way to accomplish I18N. 4483 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 4484 enough but, according to [Unicode1], 49,194 Unicode characters are 4485 already assigned. According to [Unicode2] there are still more 4486 languages that need to be added. 4488 Draft Specification NFS version 4 Protocol February 2000 4490 11.4. UTF-8 and its solutions 4492 UTF-8 solves problems for NFS that exist with the use of UCS and 4493 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 4494 that will be compact for most users. The encoding table from UCS-4 to 4495 UTF-8, as copied from [RFC2279]: 4497 UCS-4 range (hex.) UTF-8 octet sequence (binary) 4498 0000 0000-0000 007F 0xxxxxxx 4499 0000 0080-0000 07FF 110xxxxx 10xxxxxx 4500 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 4502 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 4503 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4504 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4505 10xxxxxx 4507 See [RFC2279] for precise encoding and decoding rules. Note because 4508 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 4509 for the reserved range between D800 and DFFF. 4511 Note that the 16 bit UCS or Unicode characters require no more than 3 4512 octets to encode into UTF-8 4514 Interestingly, UTF-8 has room to handle characters larger than 31 4515 bits, because the leading octet of form: 4517 1111111x 4519 is not defined. If needed, ISO could either use that octet to 4520 indicate a sequence of an encoded 8 octet character, or perhaps use 4521 11111110 to permit the next octet to indicate an even more expandable 4522 character set. 4524 So using UTF-8 to represent character encodings means never having to 4525 run out of room. 4527 11.5. Normalization 4529 The client and server operating environments may differ in their 4530 policies and operational methods with respect to character 4531 normalization (See [Unicode1] for a discussion of normalization 4532 forms). This difference may also exist between applications on the 4533 same client. This adds to the difficulty of providing a single 4534 normalization policy for the protocol that allows for maximal 4535 interoperability. This issue is similar to the character case issues 4536 where the server may or may not support case insensitive file name 4537 matching and may or may not preserve the character case when storing 4539 Draft Specification NFS version 4 Protocol February 2000 4541 file names. The protocol does not mandate a particular behavior but 4542 allows for the various permutations. 4544 The NFS version 4 protocol does not mandate the use of a particular 4545 normalization form at this time. A later revision of this 4546 specification may specify a particular normalization form. 4547 Therefore, the server and client can expect that they may receive 4548 unnormalized characters within protocol requests and responses. If 4549 the operating environment requires normalization, then the 4550 implementation must normalize the various UTF-8 encoded strings 4551 within the protocol before presenting the information to an 4552 application (at the client) or local file system (at the server). 4554 Draft Specification NFS version 4 Protocol February 2000 4556 12. Error Definitions 4558 NFS error numbers are assigned to failed operations within a compound 4559 request. A compound request contains a number of NFS operations that 4560 have their results encoded in sequence in a compound reply. The 4561 results of successful operations will consist of an NFS4_OK status 4562 followed by the encoded results of the operation. If an NFS 4563 operation fails, an error status will be entered in the reply and the 4564 compound request will be terminated. 4566 A description of each defined error follows: 4568 NFS4_OK Indicates the operation completed successfully. 4570 NFS4ERR_ACCES Permission denied. The caller does not have the 4571 correct permission to perform the requested 4572 operation. Contrast this with NFS4ERR_PERM, 4573 which restricts itself to owner or privileged 4574 user permission failures. 4576 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 4577 internal consistency checks. 4579 NFS4ERR_BADTYPE An attempt was made to create an object of a 4580 type not supported by the server. 4582 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 4584 NFS4ERR_BAD_SEQID The sequence number in a locking request is 4585 neither the next expected number or the last 4586 number processed. 4588 NFS4ERR_BAD_STATEID A stateid generated by the current server 4589 instance, but which does not designate any 4590 locking state (either current or superseded) 4591 for a current lockowner-file pair, was used. 4593 NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a 4594 client id is already in use by another client. 4596 NFS4ERR_DELAY The server initiated the request, but was not 4597 able to complete it in a timely fashion. The 4598 client should wait and then try the request 4599 with a new RPC transaction ID. For example, 4600 this error should be returned from a server 4601 that supports hierarchical storage and receives 4603 Draft Specification NFS version 4 Protocol February 2000 4605 a request to process a file that has been 4606 migrated. In this case, the server should start 4607 the immigration process and respond to client 4608 with this error. This error may also occur 4609 when a necessary delegation recall makes 4610 processing a request in a timely fashion 4611 impossible. 4613 NFS4ERR_DENIED An attempt to lock a file is denied. Since 4614 this may be a temporary condition, the client 4615 is encouraged to retry the lock request until 4616 the lock is accepted. 4618 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The 4619 user's resource limit on the server has been 4620 exceeded. 4622 NFS4ERR_EXIST File exists. The file specified already exists. 4624 NFS4ERR_EXPIRED A lease has expired that is being used in the 4625 current procedure. 4627 NFS4ERR_FBIG File too large. The operation would have caused 4628 a file to grow beyond the server's limit. 4630 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 4631 expired at the server. 4633 NFS4ERR_GRACE The server is in its recovery or grace period 4634 which should match the lease period of the 4635 server. 4637 NFS4ERR_INVAL Invalid argument or unsupported argument for an 4638 operation. Two examples are attempting a 4639 READLINK on an object other than a symbolic 4640 link or attempting to SETATTR a time field on a 4641 server that does not support this operation. 4643 NFS4ERR_IO I/O error. A hard error (for example, a disk 4644 error) occurred while processing the requested 4645 operation. 4647 NFS4ERR_ISDIR Is a directory. The caller specified a 4648 directory in a non-directory operation. 4650 NFS4ERR_LOCKED A read or write operation was attempted on a 4651 locked file. 4653 Draft Specification NFS version 4 Protocol February 2000 4655 NFS4ERR_LOCK_RANGE A lock request is operating on a sub-range of a 4656 current lock for the lock owner and the server 4657 does not support this type of request. 4659 NFS4ERR_MINOR_VERS_MISMATCH 4660 The server has received a request that 4661 specifies an unsupported minor version. The 4662 server must return a COMPOUND4res with a zero 4663 length operations result array. 4665 NFS4ERR_MLINK Too many hard links. 4667 NFS4ERR_MOVED The filesystem which contains the current 4668 filehandle object has been relocated or 4669 migrated to another server. The client may 4670 obtain the new filesystem location by obtaining 4671 the "fs_locations" attribute for the current 4672 filehandle. For further discussion, refer to 4673 the section "Filesystem Migration or 4674 Relocation". 4676 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 4678 NFS4ERR_NODEV No such device. 4680 NFS4ERR_NOENT No such file or directory. The file or 4681 directory name specified does not exist. 4683 NFS4ERR_NOFILEHANDLE The logical current file handle value has not 4684 been set properly. This may be a result of a 4685 malformed COMPOUND operation (i.e. no PUTFH or 4686 PUTROOTFH before an operation that requires the 4687 current file handle be set). 4689 NFS4ERR_NOSPC No space left on device. The operation would 4690 have caused the server's file system to exceed 4691 its limit. 4693 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 4694 directory in a directory operation. 4696 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 4697 was not empty. 4699 NFS4ERR_NOTSUPP Operation is not supported. 4701 NFS4ERR_NOT_SAME This error is returned by the VERIFY operation 4702 to signify that the attributes compared were 4704 Draft Specification NFS version 4 Protocol February 2000 4706 not the same as provided in the client's 4707 request. 4709 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 4710 during a SETATTR operation. 4712 NFS4ERR_NXIO I/O error. No such device or address. 4714 NFS4ERR_OLD_STATEID A stateid which designates the locking state 4715 for a lockowner-file at an earlier time was 4716 used. 4718 NFS4ERR_PERM Not owner. The operation was not allowed 4719 because the caller is either not a privileged 4720 user (root) or not the owner of the target of 4721 the operation. 4723 NFS4ERR_READDIR_NOSPC The encoded response to a READDIR request 4724 exceeds the size limit set by the initial 4725 request. 4727 NFS4ERR_RESOURCE For the processing of the COMPOUND procedure, 4728 the server may exhaust available resources and 4729 can not continue processing procedures within 4730 the COMPOUND operation. This error will be 4731 returned from the server in those instances of 4732 resource exhaustion related to the processing 4733 of the COMPOUND procedure. 4735 NFS4ERR_ROFS Read-only file system. A modifying operation 4736 was attempted on a read-only file system. 4738 NFS4ERR_SAME This error is returned by the NVERIFY operation 4739 to signify that the attributes compared were 4740 the same as provided in the client's request. 4742 NFS4ERR_SERVERFAULT An error occurred on the server which does not 4743 map to any of the legal NFS version 4 protocol 4744 error values. The client should translate this 4745 into an appropriate error. UNIX clients may 4746 choose to translate this to EIO. 4748 NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share 4749 reservation has failed because of a share 4750 conflict. 4752 NFS4ERR_STALE Invalid file handle. The file handle given in 4753 the arguments was invalid. The file referred to 4755 Draft Specification NFS version 4 Protocol February 2000 4757 by that file handle no longer exists or access 4758 to it has been revoked. 4760 NFS4ERR_STALE_CLIENTID A clientid not recognized by the server was 4761 used in a locking or SETCLIENTID_CONFIRM 4762 request. 4764 NFS4ERR_STALE_STATEID A stateid generated by an earlier server 4765 instance was used. 4767 NFS4ERR_SYMLINK The current file handle provided for a LOOKUP 4768 is not a directory but a symbolic link. 4770 NFS4ERR_TOOSMALL Buffer or request is too small. 4772 NFS4ERR_WRONGSEC The security mechanism being used by the client 4773 for the procedure does not match the server's 4774 security policy. The client should change the 4775 security mechanism being used and retry the 4776 operation. 4778 NFS4ERR_XDEV Attempt to do a cross-device hard link. 4780 Draft Specification NFS version 4 Protocol February 2000 4782 13. NFS Version 4 Requests 4784 For the NFS version 4 RPC program, there are two traditional RPC 4785 procedures: NULL and COMPOUND. All other functionality is defined as 4786 a set of operations and these operations are defined in normal 4787 XDR/RPC syntax and semantics. However, these operations are 4788 encapsulated within the COMPOUND procedure. This requires that the 4789 client combine one or more of the NFS version 4 operations into a 4790 single request. 4792 The NFS4_CALLBACK program is used to provide server to client 4793 signaling and is constructed in a similar fashion as the NFS version 4794 4 program. The procedures CB_NULL and CB_COMPOUND are defined in the 4795 same way as NULL and COMPOUND are within the NFS program. The 4796 CB_COMPOUND request also encapsulates the remaining operations of the 4797 NFS4_CALLBACK program. There is no predefined RPC program number for 4798 the NFS4_CALLBACK program. It is up to the client to specify a 4799 program number in the "transient" program range. The program and 4800 port number of the NFS4_CALLBACK program are provided by the client 4801 as part of the SETCLIENTID operation and therefore is fixed for the 4802 life of the client instantiation. 4804 13.1. Compound Procedure 4806 The COMPOUND procedure provides the opportunity for better 4807 performance within high latency networks. The client can avoid 4808 cumulative latency of multiple RPCs by combining multiple dependent 4809 operations into a single COMPOUND procedure. A compound operation 4810 may provide for protocol simplification by allowing the client to 4811 combine basic procedures into a single request that is customized for 4812 the client's environment. 4814 The CB_COMPOUND procedure precisely parallels the features of 4815 COMPOUND as described above. 4817 The basics of the COMPOUND procedures construction is: 4819 +-----------+-----------+-----------+-- 4820 | op + args | op + args | op + args | 4821 +-----------+-----------+-----------+-- 4823 and the reply looks like this: 4825 +------------+-----------------------+-----------------------+-- 4826 |last status | status + op + results | status + op + results | 4827 +------------+-----------------------+-----------------------+-- 4829 Draft Specification NFS version 4 Protocol February 2000 4831 13.2. Evaluation of a Compound Request 4833 The server will process the COMPOUND procedure by evaluating each of 4834 the operations within the COMPOUND procedure in order. Each 4835 component operation consists of a 32 bit operation code, followed by 4836 the argument of length determined by the type of operation. The 4837 results of each operation are encoded in sequence into a reply 4838 buffer. The results of each operation are preceded by the opcode and 4839 a status code (normally zero). If an operation results in a non-zero 4840 status code, the status will be encoded and evaluation of the 4841 compound sequence will halt and the reply will be returned. 4843 There are no atomicity requirements for the operations contained 4844 within the COMPOUND procedure. The operations being evaluated as 4845 part of a COMPOUND request may be evaluated simultaneously with other 4846 COMPOUND requests that the server receives. 4848 It is the client's responsibility for recovering from any partially 4849 completed COMPOUND procedure. Partially completed COMPOUND 4850 procedures may occur at any point due to errors such as 4851 NFS4ERR_RESOURCE and NFS4ERR_LONG_DELAY. This may occur even given 4852 an otherwise valid operation string. Further, a server reboot which 4853 occurs in the middle of processing a COMPOUND procedure may leave the 4854 client with the difficult task of determining how far COMPOUND 4855 processing has proceeded. Therefore, the client should avoid overly 4856 complex COMPOUND procedures in the event of the failure of an 4857 operation within the procedure. 4859 Each operation assumes a "current" and "saved" filehandle that is 4860 available as part of the execution context of the compound request. 4861 Operations may set, change, or return the current filehandle. The 4862 "saved" filehandle is used for temporary storage of a filehandle 4863 value and as operands for the RENAME and LINK operations. 4865 13.3. Synchronous Modifying Operations 4867 NFS version 4 operations that modify the file system are synchronous. 4868 When an operation is successfully completed at the server, the client 4869 can depend that any data associated with the request is now on stable 4870 storage. This implies that any previous operations within the same 4871 compound request are also reflected in stable storage. This behavior 4872 enables the client's ability to recover from a partially executed 4873 compound request which may resulted from the failure of the server. 4874 For example, if a compound request contains operations A and B and 4875 the server is unable to send a response to the client, depending on 4876 the progress the server made in servicing the request the result of 4877 both operations may be reflected in stable storage or just operation 4879 Draft Specification NFS version 4 Protocol February 2000 4881 A may be reflected. The server must not have just the results of 4882 operation B in stable storage. 4884 13.4. Operation Values 4886 The operations encoded in the COMPOUND procedure are identified by 4887 operation values. To avoid overlap with the RPC procedure numbers, 4888 operations 0 (zero) and 1 are not defined. Operation 2 is not 4889 defined but reserved for future use with minor versioning. 4891 Draft Specification NFS version 4 Protocol February 2000 4893 14. NFS Version 4 Procedures 4895 14.1. Procedure 0: NULL - No Operation 4897 SYNOPSIS 4899 4901 ARGUMENT 4903 void; 4905 RESULT 4907 void; 4909 DESCRIPTION 4911 Standard NULL procedure. Void argument, void response. This 4912 procedure has no functionality associated with it. Because of this 4913 it is sometimes used to measure the overhead of processing a 4914 service request. Therefore, the server should ensure that no 4915 unnecessary work is done in servicing this procedure. 4917 ERRORS 4919 None. 4921 Draft Specification NFS version 4 Protocol February 2000 4923 14.2. Procedure 1: COMPOUND - Compound Operations 4925 SYNOPSIS 4927 compoundargs -> compoundres 4929 ARGUMENT 4931 union nfs_argop4 switch (nfs_opnum4 argop) { 4932 case : ; 4933 ... 4934 }; 4936 struct COMPOUND4args { 4937 utf8string tag; 4938 uint32_t minorversion; 4939 nfs_argop4 argarray<>; 4940 }; 4942 RESULT 4944 union nfs_resop4 switch (nfs_opnum4 resop){ 4945 case : ; 4946 ... 4947 }; 4949 struct COMPOUND4res { 4950 nfsstat4 status; 4951 utf8string tag; 4952 nfs_resop4 resarray<>; 4953 }; 4955 DESCRIPTION 4957 The COMPOUND procedure is used to combine one or more of the NFS 4958 operations into a single RPC request. The main NFS RPC program has 4959 two main procedures: NULL and COMPOUND. All other operations use 4960 the COMPOUND procedure as a wrapper. 4962 The COMPOUND procedure is used to combine individual operations 4963 into a single RPC request. The server interprets each of the 4964 operations in turn. If an operation is executed by the server and 4965 the status of that operation is NFS4_OK, then the next operation in 4967 Draft Specification NFS version 4 Protocol February 2000 4969 the COMPOUND procedure is executed. The server continues this 4970 process until there are no more operations to be executed or one of 4971 the operations has a status value other than NFS4_OK. 4973 In the processing of the COMPOUND procedure, the server may find 4974 that it does not have the available resources to execute any or all 4975 of the operations within the COMPOUND sequence. In this case, the 4976 error NFS4ERR_RESOURCE will be returned for the particular 4977 operation within the COMPOUND procedure where the resource 4978 exhaustion occurred. This assumes that all previous operations 4979 within the COMPOUND sequence have been evaluated successfully. The 4980 results for all of the evaluated operations must be returned to the 4981 client. 4983 The COMPOUND arguments contain a "minorversion" field. The initial 4984 and default value for this field is 0 (zero). This field will be 4985 used by future minor versions such that the client can communicate 4986 to the server what minor version is being requested. If the server 4987 receives a COMPOUND procedure with a minorversion field value that 4988 it does not support, the server MUST return an error of 4989 NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata array. 4991 Contained within the COMPOUND results is a "status" field. If the 4992 results array length is non-zero, this status must be equivalent to 4993 the status of the last operation that was executed within the 4994 COMPOUND procedure. Therefore, if an operation incurred an error 4995 then the "status" value will be the same error value as is being 4996 returned for the operation that failed. 4998 Note that operations, 0 (zero) and 1 (one) are not defined for the 4999 COMPOUND procedure. If the server receives an operation array with 5000 either of these included, an error of NFS4ERR_NOTSUPP must be 5001 returned. Operation 2 is not defined but reserved for future 5002 definition and use with minor versioning. If the server receives a 5003 operation array that contains operation 2 and the minorversion 5004 field has a value of 0 (zero), an error of NFS4ERR_NOTSUPP is 5005 returned. If an operation array contains an operation 2 and the 5006 minorversion field is non-zero and the server does not support the 5007 minor version, the server returns an error of 5008 NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the 5009 NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other 5010 errors. 5012 IMPLEMENTATION 5014 Note that the definition of the "tag" in both the request and 5016 Draft Specification NFS version 4 Protocol February 2000 5018 response are left to the implementor. It may be used to summarize 5019 the content of the compound request for the benefit of packet 5020 sniffers and engineers debugging implementations. 5022 Since an error of any type may occur after only a portion of the 5023 operations have been evaluated, the client must be prepared to 5024 recover from any failure. If the source of an NFS4ERR_RESOURCE 5025 error was a complex or lengthy set of operations, it is likely that 5026 if the number of operations were reduced the server would be able 5027 to evaluate them successfully. Therefore, the client is 5028 responsible for dealing with this type of complexity in recovery. 5030 ERRORS 5032 All errors defined in the protocol 5034 Draft Specification NFS version 4 Protocol February 2000 5036 14.2.1. Operation 3: ACCESS - Check Access Rights 5038 SYNOPSIS 5040 (cfh), accessreq -> supported, accessrights 5042 ARGUMENT 5044 const ACCESS4_READ = 0x00000001; 5045 const ACCESS4_LOOKUP = 0x00000002; 5046 const ACCESS4_MODIFY = 0x00000004; 5047 const ACCESS4_EXTEND = 0x00000008; 5048 const ACCESS4_DELETE = 0x00000010; 5049 const ACCESS4_EXECUTE = 0x00000020; 5051 struct ACCESS4args { 5052 /* CURRENT_FH: object */ 5053 uint32_t access; 5054 }; 5056 RESULT 5058 struct ACCESS4resok { 5059 uint32_t supported; 5060 uint32_t access; 5061 }; 5063 union ACCESS4res switch (nfsstat4 status) { 5064 case NFS4_OK: 5065 ACCESS4resok resok4; 5066 default: 5067 void; 5068 }; 5070 DESCRIPTION 5072 ACCESS determines the access rights that a user, as identified by 5073 the credentials in the RPC request, has with respect to the file 5074 system object specified by the current filehandle. The client 5075 encodes the set of access rights that are to be checked in the bit 5076 mask "access". The server checks the permissions encoded in the 5077 bit mask. If a status of NFS4_OK is returned, two bit masks are 5078 included in the response. The first, "supported", represents the 5080 Draft Specification NFS version 4 Protocol February 2000 5082 access rights for which the server can verify reliably. The 5083 second, "access", represents the access rights available to the 5084 user for the filehandle provided. On success, the current 5085 filehandle retains its value. 5087 Note that the supported field will contain only as many values as 5088 was originally sent in the arguments. For example, if the client 5089 sends an ACCESS operation with only the ACCESS4_READ value set and 5090 the server supports this value, the server will return only 5091 ACCESS4_READ even if it could have reliably checked other values. 5093 The results of this operation are necessarily advisory in nature. 5094 A return status of NFS4_OK and the appropriate bit set in the bit 5095 mask does not imply that such access will be allowed to the file 5096 system object in the future. This is because access rights can be 5097 revoked by the server at any time. 5099 The following access permissions may be requested: 5101 ACCESS4_READ Read data from file or read a directory. 5103 ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- 5104 directory objects). 5106 ACCESS4_MODIFY Rewrite existing file data or modify existing 5107 directory entries. 5109 ACCESS4_EXTEND Write new data or add directory entries. 5111 ACCESS4_DELETE Delete an existing directory entry (no meaning for 5112 non-directory objects). 5114 ACCESS4_EXECUTE Execute file (no meaning for a directory). 5116 IMPLEMENTATION 5118 In general, it is not sufficient for the client to attempt to 5119 deduce access permissions by inspecting the uid, gid, and mode 5120 fields in the file attributes or by attempting to interpret the 5121 contents of the ACL attribute. This is because the server may 5122 perform uid or gid mapping or enforce additional access control 5123 restrictions. It is also possible that the server may not be in 5124 the same ID space as the client. In these cases (and perhaps 5125 others), the client can not reliably perform an access check with 5126 only current file attributes. 5128 Draft Specification NFS version 4 Protocol February 2000 5130 In the NFS version 2 protocol, the only reliable way to determine 5131 whether an operation was allowed was to try it and see if it 5132 succeeded or failed. Using the ACCESS procedure in the NFS version 5133 4 protocol, the client can ask the server to indicate whether or 5134 not one or more classes of operations are permitted. The ACCESS 5135 operation is provided to allow clients to check before doing a 5136 series of operations. This is useful in operating systems (such as 5137 UNIX) where permission checking is done only when a directory is 5138 opened. The intent is to make the behavior of opening a remote 5139 file more consistent with the behavior of opening a local file. 5141 For the NFS version 4 protocol, the use of the ACCESS procedure 5142 when opening a regular file is deprecated in favor of using OPEN. 5144 The information returned by the server in response to an ACCESS 5145 call is not permanent. It was correct at the exact time that the 5146 server performed the checks, but not necessarily afterwards. The 5147 server can revoke access permission at any time. 5149 The client should use the effective credentials of the user to 5150 build the authentication information in the ACCESS request used to 5151 determine access rights. It is the effective user and group 5152 credentials that are used in subsequent read and write operations. 5154 Many implementations do not directly support the ACCESS_DELETE 5155 permission. Operating systems like UNIX will ignore the 5156 ACCESS_DELETE bit if set on an access request on a non-directory 5157 object. In these systems, delete permission on a file is 5158 determined by the access permissions on the directory in which the 5159 file resides, instead of being determined by the permissions of the 5160 file itself. Therefore, the mask returned enumerating which access 5161 rights can be determined will have the ACCESS_DELETE value set to 5162 0. This indicates to the client that the server was unable to 5163 check that particular access right. The ACCESS_DELETE bit in the 5164 access mask returned will then be ignored by the client. 5166 ERRORS 5168 NFS4ERR_ACCES 5169 NFS4ERR_BADHANDLE 5170 NFS4ERR_DELAY 5171 NFS4ERR_FHEXPIRED 5172 NFS4ERR_IO 5173 NFS4ERR_MOVED 5174 NFS4ERR_NOFILEHANDLE 5175 NFS4ERR_RESOURCE 5176 NFS4ERR_SERVERFAULT 5178 Draft Specification NFS version 4 Protocol February 2000 5180 NFS4ERR_STALE 5181 NFS4ERR_WRONGSEC 5183 Draft Specification NFS version 4 Protocol February 2000 5185 14.2.2. Operation 4: CLOSE - Close File 5187 SYNOPSIS 5189 (cfh), stateid -> stateid 5191 ARGUMENT 5193 struct CLOSE4args { 5194 /* CURRENT_FH: object */ 5195 seqid4 seqid 5196 stateid4 stateid; 5197 }; 5199 RESULT 5201 union CLOSE4res switch (nfsstat4 status) { 5202 case NFS4_OK: 5203 stateid4 stateid; 5204 default: 5205 void; 5206 }; 5208 DESCRIPTION 5210 The CLOSE operation releases share reservations for the file as 5211 specified by the current filehandle. The share reservations and 5212 other state information released at the server as a result of this 5213 CLOSE is only associated with the supplied stateid. The sequence 5214 id provides for the correct ordering. State associated with other 5215 OPENs is not affected. 5217 If record locks are held, the client SHOULD release all locks 5218 before issuing a CLOSE. The server MAY free all outstanding locks 5219 on CLOSE but some servers may not support the CLOSE of a file that 5220 still has record locks held. The server MUST return failure if any 5221 locks would exist after the CLOSE. 5223 On success, the current filehandle retains its value. 5225 IMPLEMENTATION 5227 Draft Specification NFS version 4 Protocol February 2000 5229 ERRORS 5231 NFS4ERR_BADHANDLE 5232 NFS4ERR_BAD_SEQID 5233 NFS4ERR_BAD_STATEID 5234 NFS4ERR_DELAY 5235 NFS4ERR_EXPIRED 5236 NFS4ERR_FHEXPIRED 5237 NFS4ERR_GRACE 5238 NFS4ERR_INVAL 5239 NFS4ERR_MOVED 5240 NFS4ERR_NOFILEHANDLE 5241 NFS4ERR_OLD_STATEID 5242 NFS4ERR_RESOURCE 5243 NFS4ERR_SERVERFAULT 5244 NFS4ERR_STALE 5245 NFS4ERR_STALE_STATEID 5247 Draft Specification NFS version 4 Protocol February 2000 5249 14.2.3. Operation 5: COMMIT - Commit Cached Data 5251 SYNOPSIS 5253 (cfh), offset, count -> verifier 5255 ARGUMENT 5257 struct COMMIT4args { 5258 /* CURRENT_FH: file */ 5259 offset4 offset; 5260 count4 count; 5261 }; 5263 RESULT 5265 struct COMMIT4resok { 5266 verifier4 writeverf; 5267 }; 5269 union COMMIT4res switch (nfsstat4 status) { 5270 case NFS4_OK: 5271 COMMIT4resok resok4; 5272 default: 5273 void; 5274 }; 5276 DESCRIPTION 5278 The COMMIT operation forces or flushes data to stable storage for 5279 the file specified by the current file handle. The flushed data is 5280 that which was previously written with a WRITE operation which had 5281 the stable field set to UNSTABLE4. 5283 The offset specifies the position within the file where the flush 5284 is to begin. An offset value of 0 (zero) means to flush data 5285 starting at the beginning of the file. The count specifies the 5286 number of bytes of data to flush. If count is 0 (zero), a flush 5287 from offset to the end of the file is done. 5289 The server returns a write verifier upon successful completion of 5290 the COMMIT. The write verifier is used by the client to determine 5291 if the server has restarted or rebooted between the initial 5292 WRITE(s) and the COMMIT. The client does this by comparing the 5293 write verifier returned from the initial writes and the verifier 5295 Draft Specification NFS version 4 Protocol February 2000 5297 returned by the COMMIT procedure. The server must vary the value 5298 of the write verifier at each server event or instantiation that 5299 may lead to a loss of uncommitted data. Most commonly this occurs 5300 when the server is rebooted; however, other events at the server 5301 may result in uncommitted data loss as well. 5303 On success, the current filehandle retains its value. 5305 IMPLEMENTATION 5307 The COMMIT procedure is similar in operation and semantics to the 5308 POSIX fsync(2) system call that synchronizes a file's state with 5309 the disk (file data and metadata is flushed to disk or stable 5310 storage). COMMIT performs the same operation for a client, flushing 5311 any unsynchronized data and metadata on the server to the server's 5312 disk or stable storage for the specified file. Like fsync(2), it 5313 may be that there is some modified data or no modified data to 5314 synchronize. The data may have been synchronized by the server's 5315 normal periodic buffer synchronization activity. COMMIT should 5316 return NFS4_OK, unless there has been an unexpected error. 5318 COMMIT differs from fsync(2) in that it is possible for the client 5319 to flush a range of the file (most likely triggered by a buffer- 5320 reclamation scheme on the client before file has been completely 5321 written). 5323 The server implementation of COMMIT is reasonably simple. If the 5324 server receives a full file COMMIT request, that is starting at 5325 offset 0 and count 0, it should do the equivalent of fsync()'ing 5326 the file. Otherwise, it should arrange to have the cached data in 5327 the range specified by offset and count to be flushed to stable 5328 storage. In both cases, any metadata associated with the file must 5329 be flushed to stable storage before returning. It is not an error 5330 for there to be nothing to flush on the server. This means that 5331 the data and metadata that needed to be flushed have already been 5332 flushed or lost during the last server failure. 5334 The client implementation of COMMIT is a little more complex. 5335 There are two reasons for wanting to commit a client buffer to 5336 stable storage. The first is that the client wants to reuse a 5337 buffer. In this case, the offset and count of the buffer are sent 5338 to the server in the COMMIT request. The server then flushes any 5339 cached data based on the offset and count, and flushes any metadata 5340 associated with the file. It then returns the status of the flush 5341 and the write verifier. The other reason for the client to 5342 generate a COMMIT is for a full file flush, such as may be done at 5343 close. In this case, the client would gather all of the buffers 5345 Draft Specification NFS version 4 Protocol February 2000 5347 for this file that contain uncommitted data, do the COMMIT 5348 operation with an offset of 0 and count of 0, and then free all of 5349 those buffers. Any other dirty buffers would be sent to the server 5350 in the normal fashion. 5352 After a buffer is written by the client with the stable parameter 5353 set to UNSTABLE4, the buffer must be considered as modified by the 5354 client until the buffer has either been flushed via a COMMIT 5355 operation or written via a WRITE operation with stable parameter 5356 set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer 5357 from being freed and reused before the data can be flushed to 5358 stable storage on the server. 5360 When a response is returned from either a WRITE or a COMMIT 5361 operation and it contains a write verifier that is different than 5362 previously returned by the server, the client will need to 5363 retransmit all of the buffers containing uncommitted cached data to 5364 the server. How this is to be done is up to the implementor. If 5365 there is only one buffer of interest, then it should probably be 5366 sent back over in a WRITE request with the appropriate stable 5367 parameter. If there is more than one buffer, it might be 5368 worthwhile retransmitting all of the buffers in WRITE requests with 5369 the stable parameter set to UNSTABLE4 and then retransmitting the 5370 COMMIT operation to flush all of the data on the server to stable 5371 storage. The timing of these retransmissions is left to the 5372 implementor. 5374 The above description applies to page-cache-based systems as well 5375 as buffer-cache-based systems. In those systems, the virtual 5376 memory system will need to be modified instead of the buffer cache. 5378 ERRORS 5380 NFS4ERR_ACCES 5381 NFS4ERR_BADHANDLE 5382 NFS4ERR_FHEXPIRED 5383 NFS4ERR_IO 5384 NFS4ERR_LOCKED 5385 NFS4ERR_MOVED 5386 NFS4ERR_NOFILEHANDLE 5387 NFS4ERR_RESOURCE 5388 NFS4ERR_ROFS 5389 NFS4ERR_SERVERFAULT 5390 NFS4ERR_STALE 5391 NFS4ERR_WRONGSEC 5393 Draft Specification NFS version 4 Protocol February 2000 5395 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 5397 SYNOPSIS 5399 (cfh), name, type -> (cfh), change_info 5401 ARGUMENT 5403 union createtype4 switch (nfs_ftype4 type) { 5404 case NF4LNK: 5405 linktext4 linkdata; 5406 case NF4BLK: 5407 case NF4CHR: 5408 specdata4 devdata; 5409 case NF4SOCK: 5410 case NF4FIFO: 5411 case NF4DIR: 5412 void; 5413 }; 5415 struct CREATE4args { 5416 /* CURRENT_FH: directory for creation */ 5417 component4 objname; 5418 createtype4 objtype; 5419 }; 5421 RESULT 5423 struct CREATE4resok { 5424 change_info4 cinfo; 5425 }; 5427 union CREATE4res switch (nfsstat4 status) { 5428 case NFS4_OK: 5429 CREATE4resok resok4; 5430 default: 5431 void; 5432 }; 5434 DESCRIPTION 5436 The CREATE operation creates a non-regular file object in a 5437 directory with a given name. The OPEN procedure MUST be used to 5438 create a regular file. 5440 Draft Specification NFS version 4 Protocol February 2000 5442 The objname specifies the name for the new object. If the objname 5443 has a length of 0 (zero), the error NFS4ERR_INVAL will be returned. 5444 The objtype determines the type of object to be created: directory, 5445 symlink, etc. 5447 If an object of the same name already exists in the directory, the 5448 server will return the error NFS4ERR_EXIST. 5450 For the directory where the new file object was created, the server 5451 returns change_info4 information in cinfo. With the atomic field 5452 of the change_info4 struct, the server will indicate if the before 5453 and after change attributes were obtained atomically with respect 5454 to the file object creation. 5456 If the objname has a length of 0 (zero), or if objname does not 5457 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5458 returned. 5460 The current filehandle is replaced by that of the new object. 5462 IMPLEMENTATION 5464 If the client desires to set attribute values after the create, a 5465 SETATTR operation can be added to the COMPOUND request so that the 5466 appropriate attributes will be set. 5468 ERRORS 5470 NFS4ERR_ACCES 5471 NFS4ERR_BADHANDLE 5472 NFS4ERR_BADTYPE 5473 NFS4ERR_DQUOT 5474 NFS4ERR_EXIST 5475 NFS4ERR_FHEXPIRED 5476 NFS4ERR_INVAL 5477 NFS4ERR_IO 5478 NFS4ERR_MOVED 5479 NFS4ERR_NAMETOOLONG 5480 NFS4ERR_NOFILEHANDLE 5481 NFS4ERR_NOSPC 5482 NFS4ERR_NOTDIR 5483 NFS4ERR_NOTSUPP 5484 NFS4ERR_RESOURCE 5485 NFS4ERR_ROFS 5486 NFS4ERR_SERVERFAULT 5487 NFS4ERR_STALE 5489 Draft Specification NFS version 4 Protocol February 2000 5491 NFS4ERR_WRONGSEC 5493 Draft Specification NFS version 4 Protocol February 2000 5495 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery 5497 SYNOPSIS 5499 clientid -> 5501 ARGUMENT 5503 struct DELEGPURGE4args { 5504 clientid4 clientid; 5505 }; 5507 RESULT 5509 struct DELEGPURGE4res { 5510 nfsstat4 status; 5511 }; 5513 DESCRIPTION 5515 Purges all of the delegations awaiting recovery for a given client. 5516 This is useful for clients which do not commit delegation 5517 information to stable storage to indicate that conflicting requests 5518 need not be delayed by the server awaiting recovery of delegation 5519 information. 5521 This operation should also be used by clients which do have 5522 delegation information on stable storage after doing all of 5523 delegation recovery that is needed. Using DELEGPURGE will prevent 5524 any delegations which were made by the server but were not sent to 5525 the client and committed to stable storage from holding up other 5526 clients making conflicting requests. 5528 ERRORS 5530 NFS4ERR_RESOURCE 5531 NFS4ERR_SERVERFAULT 5532 NFS4ERR_STALE_CLIENTID 5534 Draft Specification NFS version 4 Protocol February 2000 5536 14.2.6. Operation 8: DELEGRETURN - Return Delegation 5538 SYNOPSIS 5540 stateid -> 5542 ARGUMENT 5544 struct DELEGRETURN4args { 5545 stateid4 stateid; 5546 }; 5548 RESULT 5550 struct DELEGRETURN4res { 5551 nfsstat4 status; 5552 }; 5554 DESCRIPTION 5556 Returns the delegation represented by the given stateid. 5558 ERRORS 5560 NFS4ERR_BAD_STATEID 5561 NFS4ERR_OLD_STATEID 5562 NFS4ERR_RESOURCE 5563 NFS4ERR_SERVERFAULT 5564 NFS4ERR_STALE_STATEID 5566 Draft Specification NFS version 4 Protocol February 2000 5568 14.2.7. Operation 9: GETATTR - Get Attributes 5570 SYNOPSIS 5572 (cfh), attrbits -> attrbits, attrvals 5574 ARGUMENT 5576 struct GETATTR4args { 5577 /* CURRENT_FH: directory or file */ 5578 bitmap4 attr_request; 5579 }; 5581 RESULT 5583 struct GETATTR4resok { 5584 fattr4 obj_attributes; 5585 }; 5587 union GETATTR4res switch (nfsstat4 status) { 5588 case NFS4_OK: 5589 GETATTR4resok resok4; 5590 default: 5591 void; 5592 }; 5594 DESCRIPTION 5596 The GETATTR operation will obtain attributes for the file system 5597 object specified by the current filehandle. The client sets a bit 5598 in the bitmap argument for each attribute value that it would like 5599 the server to return. The server returns an attribute bitmap that 5600 indicates the attribute values for which it was able to return, 5601 followed by the attribute values ordered lowest attribute number 5602 first. 5604 The server must return a value for each attribute that the client 5605 requests if the attribute is supported by the server. If the 5606 server does not support an attribute or cannot approximate a useful 5607 value then it must not return the attribute value and must not set 5608 the attribute bit in the result bitmap. The server must return an 5609 error if it supports an attribute but cannot obtain its value. In 5610 that case no attribute values will be returned. 5612 All servers must support the mandatory attributes as specified in 5614 Draft Specification NFS version 4 Protocol February 2000 5616 the section "File Attributes". 5618 On success, the current filehandle retains its value. 5620 IMPLEMENTATION 5622 ERRORS 5624 NFS4ERR_ACCES 5625 NFS4ERR_BADHANDLE 5626 NFS4ERR_DELAY 5627 NFS4ERR_FHEXPIRED 5628 NFS4ERR_INVAL 5629 NFS4ERR_IO 5630 NFS4ERR_MOVED 5631 NFS4ERR_NOFILEHANDLE 5632 NFS4ERR_RESOURCE 5633 NFS4ERR_SERVERFAULT 5634 NFS4ERR_STALE 5635 NFS4ERR_WRONGSEC 5637 Draft Specification NFS version 4 Protocol February 2000 5639 14.2.8. Operation 10: GETFH - Get Current Filehandle 5641 SYNOPSIS 5643 (cfh) -> filehandle 5645 ARGUMENT 5647 /* CURRENT_FH: */ 5648 void; 5650 RESULT 5652 struct GETFH4resok { 5653 nfs_fh4 object; 5654 }; 5656 union GETFH4res switch (nfsstat4 status) { 5657 case NFS4_OK: 5658 GETFH4resok resok4; 5659 default: 5660 void; 5661 }; 5663 DESCRIPTION 5665 This operation returns the current filehandle value. 5667 On success, the current filehandle retains its value. 5669 IMPLEMENTATION 5671 Operations that change the current filehandle like LOOKUP or CREATE 5672 do not automatically return the new filehandle as a result. For 5673 instance, if a client needs to lookup a directory entry and obtain 5674 its filehandle then the following request is needed. 5676 PUTFH (directory filehandle) 5677 LOOKUP (entry name) 5678 GETFH 5680 ERRORS 5682 Draft Specification NFS version 4 Protocol February 2000 5684 NFS4ERR_BADHANDLE 5685 NFS4ERR_FHEXPIRED 5686 NFS4ERR_MOVED 5687 NFS4ERR_NOFILEHANDLE 5688 NFS4ERR_RESOURCE 5689 NFS4ERR_SERVERFAULT 5690 NFS4ERR_STALE 5691 NFS4ERR_WRONGSEC 5693 Draft Specification NFS version 4 Protocol February 2000 5695 14.2.9. Operation 11: LINK - Create Link to a File 5697 SYNOPSIS 5699 (sfh), (cfh), newname -> (cfh), change_info 5701 ARGUMENT 5703 struct LINK4args { 5704 /* SAVED_FH: source object */ 5705 /* CURRENT_FH: target directory */ 5706 component4 newname; 5707 }; 5709 RESULT 5711 struct LINK4resok { 5712 change_info4 cinfo; 5713 }; 5715 union LINK4res switch (nfsstat4 status) { 5716 case NFS4_OK: 5717 LINK4resok resok4; 5718 default: 5719 void; 5720 }; 5722 DESCRIPTION 5724 The LINK operation creates an additional newname for the file 5725 represented by the saved filehandle, as set by the SAVEFH 5726 operation, in the directory represented by the current filehandle. 5727 The existing file and the target directory must reside within the 5728 same file system on the server. On success, the current filehandle 5729 will continue to be the target directory. 5731 For the target directory, the server returns change_info4 5732 information in cinfo. With the atomic field of the change_info4 5733 struct, the server will indicate if the before and after change 5734 attributes were obtained atomically with respect to the link 5735 creation. 5737 If the newname has a length of 0 (zero), or if newname does not 5738 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5739 returned. 5741 Draft Specification NFS version 4 Protocol February 2000 5743 IMPLEMENTATION 5745 Changes to any property of the "hard" linked files are reflected in 5746 all of the linked files. When a link is made to a file, the 5747 attributes for the file should have a value for numlinks that is 5748 one greater than the value before the LINK operation. 5750 The comments under RENAME regarding object and target residing on 5751 the same file system apply here as well. The comments regarding the 5752 target name applies as well. 5754 ERRORS 5756 NFS4ERR_ACCES 5757 NFS4ERR_BADHANDLE 5758 NFS4ERR_DELAY 5759 NFS4ERR_DQUOT 5760 NFS4ERR_EXIST 5761 NFS4ERR_FHEXPIRED 5762 NFS4ERR_INVAL 5763 NFS4ERR_IO 5764 NFS4ERR_MLINK 5765 NFS4ERR_MOVED 5766 NFS4ERR_NAMETOOLONG 5767 NFS4ERR_NOSPC 5768 NFS4ERR_NOTDIR 5769 NFS4ERR_NOTSUPP 5770 NFS4ERR_RESOURCE 5771 NFS4ERR_ROFS 5772 NFS4ERR_SERVERFAULT 5773 NFS4ERR_STALE 5774 NFS4ERR_WRONGSEC 5775 NFS4ERR_XDEV 5777 Draft Specification NFS version 4 Protocol February 2000 5779 14.2.10. Operation 12: LOCK - Create Lock 5781 SYNOPSIS 5783 (cfh) type, seqid, reclaim, owner, offset, length -> stateid, 5784 access 5786 ARGUMENT 5788 enum nfs4_lock_type { 5789 READ_LT = 1, 5790 WRITE_LT = 2, 5791 READW_LT = 3, /* blocking read */ 5792 WRITEW_LT = 4 /* blocking write */ 5793 }; 5795 struct LOCK4args { 5796 /* CURRENT_FH: file */ 5797 nfs_lock_type4 locktype; 5798 seqid4 seqid; 5799 bool reclaim; 5800 stateid4 stateid; 5801 offset4 offset; 5802 length4 length; 5803 }; 5805 RESULT 5807 struct LOCK4denied { 5808 nfs_lockowner4 owner; 5809 offset4 offset; 5810 length4 length; 5811 }; 5813 union LOCK4res switch (nfsstat4 status) { 5814 case NFS4_OK: 5815 stateid4 stateid; 5816 case NFS4ERR_DENIED: 5817 LOCK4denied denied; 5818 default: 5819 void; 5820 }; 5822 DESCRIPTION 5824 Draft Specification NFS version 4 Protocol February 2000 5826 The LOCK operation requests a record lock for the byte range 5827 specified by the offset and length parameters. The lock type is 5828 also specified to be one of the nfs4_lock_types. If this is a 5829 reclaim request, the reclaim parameter will be TRUE; 5831 Bytes in a file may be locked even if those bytes are not currently 5832 allocated to the file. To lock the file from a specific offset 5833 through the end-of-file (no matter how long the file actually is) 5834 use a length field with all bits set to 1 (one). To lock the 5835 entire file, use an offset of 0 (zero) and a length with all bits 5836 set to 1. A length of 0 is reserved and should not be used. 5838 In the case that the lock is denied, the the owner, offset, and 5839 length of the conflicting lock are returned. 5841 On success, the current filehandle retains its value. 5843 IMPLEMENTATION 5845 If the server is unable to determine the exact offset and length of 5846 the conflicting lock, the same offset and length that were provided 5847 in the arguments should be returned in the denied results. The 5848 File Locking section contains a full description of this and the 5849 other file locking operations. 5851 ERRORS 5853 NFS4ERR_ACCES 5854 NFS4ERR_BADHANDLE 5855 NFS4ERR_BAD_SEQID 5856 NFS4ERR_BAD_STATEID 5857 NFS4ERR_DELAY 5858 NFS4ERR_DENIED 5859 NFS4ERR_EXPIRED 5860 NFS4ERR_FHEXPIRED 5861 NFS4ERR_GRACE 5862 NFS4ERR_INVAL 5863 NFS4ERR_ISDIR 5864 NFS4ERR_LOCK_RANGE 5865 NFS4ERR_MOVED 5866 NFS4ERR_NOFILEHANDLE 5867 NFS4ERR_OLD_STATEID 5868 NFS4ERR_RESOURCE 5869 NFS4ERR_SERVERFAULT 5870 NFS4ERR_STALE 5871 NFS4ERR_STALE_CLIENTID 5873 Draft Specification NFS version 4 Protocol February 2000 5875 NFS4ERR_STALE_STATEID 5876 NFS4ERR_WRONGSEC 5878 Draft Specification NFS version 4 Protocol February 2000 5880 14.2.11. Operation 13: LOCKT - Test For Lock 5882 SYNOPSIS 5884 (cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED -> 5885 owner} 5887 ARGUMENT 5889 struct LOCKT4args { 5890 /* CURRENT_FH: file */ 5891 nfs_lock_type4 locktype; 5892 nfs_lockowner4 owner; 5893 offset4 offset; 5894 length4 length; 5895 }; 5897 RESULT 5899 union LOCKT4res switch (nfsstat4 status) { 5900 case NFS4ERR_DENIED: 5901 LOCK4denied denied; 5902 case NFS4_OK: 5903 void; 5904 default: 5905 void; 5906 }; 5908 DESCRIPTION 5910 The LOCKT operation tests the lock as specified in the arguments. 5911 If a conflicting lock exists, the owner, offset, and length of the 5912 conflicting lock are returned; if no lock is held, nothing other 5913 than NFS4_OK is returned. 5915 On success, the current filehandle retains its value. 5917 IMPLEMENTATION 5919 If the server is unable to determine the exact offset and length of 5920 the conflicting lock, the same offset and length that were provided 5921 in the arguments should be returned in the denied results. The 5922 File Locking section contains further discussion of the file 5924 Draft Specification NFS version 4 Protocol February 2000 5926 locking mechanisms. 5928 ERRORS 5930 NFS4ERR_ACCES 5931 NFS4ERR_BADHANDLE 5932 NFS4ERR_DELAY 5933 NFS4ERR_DENIED 5934 NFS4ERR_FHEXPIRED 5935 NFS4ERR_GRACE 5936 NFS4ERR_INVAL 5937 NFS4ERR_ISDIR 5938 NFS4ERR_LOCK_RANGE 5939 NFS4ERR_MOVED 5940 NFS4ERR_NOFILEHANDLE 5941 NFS4ERR_RESOURCE 5942 NFS4ERR_SERVERFAULT 5943 NFS4ERR_STALE 5944 NFS4ERR_STALE_CLIENTID 5945 NFS4ERR_WRONGSEC 5947 Draft Specification NFS version 4 Protocol February 2000 5949 14.2.12. Operation 14: LOCKU - Unlock File 5951 SYNOPSIS 5953 (cfh) type, seqid, stateid, offset, length -> stateid 5955 ARGUMENT 5957 struct LOCKU4args { 5958 /* CURRENT_FH: file */ 5959 nfs_lock_type4 type; 5960 seqid4 seqid; 5961 stateid4 stateid; 5962 offset4 offset; 5963 length4 length; 5964 }; 5966 RESULT 5968 union LOCKU4res switch (nfsstat4 status) { 5969 case NFS4_OK: 5970 stateid4 stateid; 5971 default: 5972 void; 5973 }; 5975 DESCRIPTION 5977 The LOCKU operation unlocks the record lock specified by the 5978 parameters. 5980 On success, the current filehandle retains its value. 5982 IMPLEMENTATION 5984 The File Locking section contains a full description of this and 5985 the other file locking procedures. 5987 ERRORS 5989 NFS4ERR_ACCES 5990 NFS4ERR_BADHANDLE 5991 NFS4ERR_BAD_SEQID 5993 Draft Specification NFS version 4 Protocol February 2000 5995 NFS4ERR_BAD_STATEID 5996 NFS4ERR_EXPIRED 5997 NFS4ERR_FHEXPIRED 5998 NFS4ERR_GRACE 5999 NFS4ERR_INVAL 6000 NFS4ERR_LOCK_RANGE 6001 NFS4ERR_MOVED 6002 NFS4ERR_NOFILEHANDLE 6003 NFS4ERR_OLD_STATEID 6004 NFS4ERR_RESOURCE 6005 NFS4ERR_SERVERFAULT 6006 NFS4ERR_STALE 6007 NFS4ERR_STALE_CLIENTID 6008 NFS4ERR_STALE_STATEID 6010 Draft Specification NFS version 4 Protocol February 2000 6012 14.2.13. Operation 15: LOOKUP - Lookup Filename 6014 SYNOPSIS 6016 (cfh), filenames -> (cfh) 6018 ARGUMENT 6020 struct LOOKUP4args { 6021 /* CURRENT_FH: directory */ 6022 pathname4 path; 6023 }; 6025 RESULT 6027 struct LOOKUP4res { 6028 /* CURRENT_FH: object */ 6029 nfsstat4 status; 6030 }; 6032 DESCRIPTION 6034 This operation LOOKUPs or finds a file system object starting from 6035 the directory specified by the current filehandle. LOOKUP 6036 evaluates the pathname contained in the array of names and obtains 6037 a new current filehandle from the final name. All but the final 6038 name in the list must be the names of directories. 6040 If the pathname cannot be evaluated either because a component does 6041 not exist or because the client does not have permission to 6042 evaluate a component of the path, then an error will be returned 6043 and the current filehandle will be unchanged. 6045 If the path is a zero length array, if any component does not obey 6046 the UTF-8 definition, or if any component in the path is of zero 6047 length, the error NFS4ERR_INVAL will be returned. 6049 IMPLEMENTATION 6051 If the client prefers a partial evaluation of the path then a 6052 sequence of LOOKUP operations can be substituted e.g. 6054 Draft Specification NFS version 4 Protocol February 2000 6056 PUTFH (directory filehandle) 6057 LOOKUP "pub" "foo" "bar" 6058 GETFH 6060 or 6062 PUTFH (directory filehandle) 6063 LOOKUP "pub" 6064 GETFH 6065 LOOKUP "foo" 6066 GETFH 6067 LOOKUP "bar" 6068 GETFH 6070 NFS version 4 servers depart from the semantics of previous NFS 6071 versions in allowing LOOKUP requests to cross mountpoints on the 6072 server. The client can detect a mountpoint crossing by comparing 6073 the fsid attribute of the directory with the fsid attribute of the 6074 directory looked up. If the fsids are different then the new 6075 directory is a server mountpoint. Unix clients that detect a 6076 mountpoint crossing will need to mount the server's filesystem. 6078 Servers that limit NFS access to "shares" or "exported" filesystems 6079 should provide a pseudo-filesystem into which the exported 6080 filesystems can be integrated, so that clients can browse the 6081 server's name space. The clients view of a pseudo filesystem will 6082 be limited to paths that lead to exported filesystems. 6084 Note: previous versions of the protocol assigned special semantics 6085 to the names "." and "..". NFS version 4 assigns no special 6086 semantics to these names. The LOOKUPP operator must be used to 6087 lookup a parent directory. 6089 Note that this procedure does not follow symbolic links. The 6090 client is responsible for all parsing of filenames including 6091 filenames that are modified by symbolic links encountered during 6092 the lookup process. 6094 If the current file handle supplied is not a directory but a 6095 symbolic link, the error NFS4ERR_SYMLINK is returned as the error. 6096 For all other non-directory file types, the error NFS4ERR_NOTDIR is 6097 returned. 6099 ERRORS 6101 NFS4ERR_ACCES 6103 Draft Specification NFS version 4 Protocol February 2000 6105 NFS4ERR_BADHANDLE 6106 NFS4ERR_FHEXPIRED 6107 NFS4ERR_INVAL 6108 NFS4ERR_IO 6109 NFS4ERR_MOVED 6110 NFS4ERR_NAMETOOLONG 6111 NFS4ERR_NOENT 6112 NFS4ERR_NOFILEHANDLE 6113 NFS4ERR_NOTDIR 6114 NFS4ERR_RESOURCE 6115 NFS4ERR_SERVERFAULT 6116 NFS4ERR_STALE 6117 NFS4ERR_SYMLINK 6118 NFS4ERR_WRONGSEC 6120 Draft Specification NFS version 4 Protocol February 2000 6122 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory 6124 SYNOPSIS 6126 (cfh) -> (cfh) 6128 ARGUMENT 6130 /* CURRENT_FH: object */ 6131 void; 6133 RESULT 6135 struct LOOKUPP4res { 6136 /* CURRENT_FH: directory */ 6137 nfsstat4 status; 6138 }; 6140 DESCRIPTION 6142 The current filehandle is assumed to refer to a regular directory 6143 or a named attribute directory. LOOKUPP assigns the filehandle for 6144 its parent directory to be the current filehandle. If there is no 6145 parent directory an NFS4ERR_ENOENT error must be returned. 6146 Therefore, NFS4ERR_ENOENT will be returned by the server when the 6147 current filehandle is at the root or top of the server's file tree. 6149 IMPLEMENTATION 6151 As for LOOKUP, LOOKUPP will also cross mountpoints. 6153 If the current filehandle is not a directory or named attribute 6154 directory, the error NFS4ERR_NOTDIR is returned. 6156 ERRORS 6158 NFS4ERR_ACCES 6159 NFS4ERR_BADHANDLE 6160 NFS4ERR_FHEXPIRED 6161 NFS4ERR_INVAL 6162 NFS4ERR_IO 6163 NFS4ERR_MOVED 6164 NFS4ERR_NOENT 6165 NFS4ERR_NOFILEHANDLE 6167 Draft Specification NFS version 4 Protocol February 2000 6169 NFS4ERR_NOTDIR 6170 NFS4ERR_RESOURCE 6171 NFS4ERR_SERVERFAULT 6172 NFS4ERR_STALE 6173 NFS4ERR_WRONGSEC 6175 Draft Specification NFS version 4 Protocol February 2000 6177 14.2.15. Operation 17: NVERIFY - Verify Difference in Attributes 6179 SYNOPSIS 6181 (cfh), attrbits, attrvals -> - 6183 ARGUMENT 6185 struct NVERIFY4args { 6186 /* CURRENT_FH: object */ 6187 bitmap4 attr_request; 6188 fattr4 obj_attributes; 6189 }; 6191 RESULT 6193 struct NVERIFY4res { 6194 nfsstat4 status; 6195 }; 6197 DESCRIPTION 6199 This operation is used to prefix a sequence of operations to be 6200 performed if one or more attributes have changed on some filesystem 6201 object. If all the attributes match then the error NFS4ERR_SAME 6202 must be returned. 6204 IMPLEMENTATION 6206 This operation is useful as a cache validation operator. If the 6207 object to which the attributes belong has changed then the 6208 following operations may obtain new data associated with that 6209 object. For instance, to check if a file has been changed and 6210 obtain new data if it has: 6212 PUTFH (public) 6213 LOOKUP "pub" "foo" "bar" 6214 NVERIFY attrbits attrs 6215 READ 0 32767 6217 In the case that a recommended attribute is specified in the 6218 NVERIFY operation and the server does not support that attribute 6219 for the file system object, the error NFS4ERR_NOTSUPP is returned 6221 Draft Specification NFS version 4 Protocol February 2000 6223 to the client. 6225 ERRORS 6227 NFS4ERR_ACCES 6228 NFS4ERR_BADHANDLE 6229 NFS4ERR_DELAY 6230 NFS4ERR_FHEXPIRED 6231 NFS4ERR_INVAL 6232 NFS4ERR_IO 6233 NFS4ERR_MOVED 6234 NFS4ERR_NOFILEHANDLE 6235 NFS4ERR_NOTSUPP 6236 NFS4ERR_RESOURCE 6237 NFS4ERR_SAME 6238 NFS4ERR_SERVERFAULT 6239 NFS4ERR_STALE 6240 NFS4ERR_WRONGSEC 6242 Draft Specification NFS version 4 Protocol February 2000 6244 14.2.16. Operation 18: OPEN - Open a Regular File 6246 SYNOPSIS 6248 (cfh), claim, openhow, owner, seqid, access, deny -> (cfh), 6249 stateid, cinfo, rflags, open_confirm, delegation 6251 ARGUMENT 6253 struct OPEN4args { 6254 open_claim4 claim; 6255 openflag4 openhow; 6256 nfs_lockowner4 owner; 6257 seqid4 seqid; 6258 uint32_t share_access; 6259 uint32_t share_deny; 6260 }; 6262 enum createmode4 { 6263 UNCHECKED4 = 0, 6264 GUARDED4 = 1, 6265 EXCLUSIVE4 = 2 6266 }; 6268 union createhow4 switch (createmode4 mode) { 6269 case UNCHECKED4: 6270 case GUARDED4: 6271 fattr4 createattrs; 6272 case EXCLUSIVE4: 6273 verifier4 createverf; 6274 }; 6276 enum opentype4 { 6277 OPEN4_NOCREATE = 0, 6278 OPEN4_CREATE = 1 6279 }; 6281 union openflag4 switch (opentype4 opentype) { 6282 case OPEN4_CREATE: 6283 createhow4 how; 6284 default: 6285 void; 6286 }; 6288 /* Next definitions used for OPEN delegation */ 6289 enum limit_by4 { 6290 NFS_LIMIT_SIZE = 1, 6292 Draft Specification NFS version 4 Protocol February 2000 6294 NFS_LIMIT_BLOCKS = 2 6295 /* others as needed */ 6296 }; 6298 struct nfs_modified_limit4 { 6299 uint32_t num_blocks; 6300 uint32_t bytes_per_block; 6301 }; 6303 union nfs_space_limit4 switch (limit_by4 limitby) { 6304 /* limit specified as file size */ 6305 case NFS_LIMIT_SIZE: 6306 uint64_t filesize; 6307 /* limit specified by number of blocks */ 6308 case NFS_LIMIT_BLOCKS: 6309 nfs_modified_limit4 mod_blocks; 6310 } ; 6312 enum open_delegation_type4 { 6313 OPEN_DELEGATE_NONE = 0, 6314 OPEN_DELEGATE_READ = 1, 6315 OPEN_DELEGATE_WRITE = 2 6316 }; 6318 enum open_claim_type4 { 6319 CLAIM_NULL = 0, 6320 CLAIM_PREVIOUS = 1, 6321 CLAIM_DELEGATE_CUR = 2, 6322 CLAIM_DELEGATE_PREV = 3 6323 }; 6325 struct open_claim_delegate_cur4 { 6326 pathname4 file; 6327 stateid4 delegate_stateid; 6328 }; 6330 union open_claim4 switch (open_claim_type4 claim) { 6331 /* 6332 * No special rights to file. Ordinary OPEN of the specified file. 6333 */ 6334 case CLAIM_NULL: 6335 /* CURRENT_FH: directory */ 6336 pathname4 file; 6338 /* 6339 * Right to the file established by an open previous to server 6340 * reboot. File identified by filehandle obtained at that time 6341 * rather than by name. 6343 Draft Specification NFS version 4 Protocol February 2000 6345 */ 6346 case CLAIM_PREVIOUS: 6347 /* CURRENT_FH: file being reclaimed */ 6348 uint32_t delegate_type; 6350 /* 6351 * Right to file based on a delegation granted by the server. 6352 * File is specified by name. 6353 */ 6354 case CLAIM_DELEGATE_CUR: 6355 /* CURRENT_FH: directory */ 6356 open_claim_delegate_cur4 delegate_cur_info; 6358 /* Right to file based on a delegation granted to a previous boot 6359 * instance of the client. File is specified by name. 6360 */ 6361 case CLAIM_DELEGATE_PREV: 6362 /* CURRENT_FH: directory */ 6363 pathname4 file_delegate_prev; 6364 }; 6366 RESULT 6368 struct open_read_delegation4 { 6369 stateid4 stateid; /* Stateid for delegation*/ 6370 bool recall; /* Pre-recalled flag for 6371 delegations obtained 6372 by reclaim 6373 (CLAIM_PREVIOUS) */ 6374 nfsace4 permissions; /* Defines users who don't 6375 need an ACCESS call to 6376 open for read */ 6377 }; 6379 struct open_write_delegation4 { 6380 stateid4 stateid; /* Stateid for delegation 6381 be flushed to the server 6382 on close. */ 6383 bool recall; /* Pre-recalled flag for 6384 delegations obtained 6385 by reclaim 6386 (CLAIM_PREVIOUS) */ 6387 nfs_space_limit4 space_limit; /* Defines condition that 6388 the client must check to 6389 determine whether the 6390 file needs to be flushed 6392 Draft Specification NFS version 4 Protocol February 2000 6394 to the server on close. 6395 */ 6396 nfsace4 permissions; /* Defines users who don't 6397 need an ACCESS call as 6398 part of a delegated 6399 open. */ 6400 }; 6402 union open_delegation4 6403 switch (open_delegation_type4 delegation_type) { 6404 case OPEN_DELEGATE_NONE: 6405 void; 6406 case OPEN_DELEGATE_READ: 6407 open_read_delegation4 read; 6408 case OPEN_DELEGATE_WRITE: 6409 open_write_delegation4 write; 6410 }; 6412 const OPEN4_RESULT_MLOCK = 0x00000001; 6413 const OPEN4_RESULT_CONFIRM= 0x00000002; 6415 struct OPEN4resok { 6416 stateid4 stateid; /* Stateid for open */ 6417 change_info4 cinfo; /* Directory Change Info */ 6418 uint32_t rflags; /* Result flags */ 6419 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 6420 open_delegation4 delegation; /* Info on any open 6421 delegation */ 6422 }; 6424 union OPEN4res switch (nfsstat4 status) { 6425 case NFS4_OK: 6426 /* CURRENT_FH: opened file */ 6427 OPEN4resok result; 6428 default: 6429 void; 6430 }; 6432 DESCRIPTION 6434 The OPEN operation creates and/or opens a regular file in a 6435 directory with the provided name. If the file does not exist at 6436 the server and creation is desired, specification of the method of 6437 creation is provided by the openhow parameter. The client has the 6438 choice of three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE. 6440 UNCHECKED means that the file should be created if a file of that 6442 Draft Specification NFS version 4 Protocol February 2000 6444 name does not exist and encountering an existing regular file of 6445 that name is not an error. For this type of create, createattrs 6446 specifies the initial set of attributes for the file. The set of 6447 attributes may includes any writable attribute valid for regular 6448 files. When an UNCHECKED create encounters an existing file, the 6449 attributes specified by createattrs is not used, except that when 6450 an object_size of zero is specified, the existing file is 6451 truncated. If GUARDED is specified, the server checks for the 6452 presence of a duplicate object by name before performing the 6453 create. If a duplicate exists, an error of NFS4ERR_EXIST is 6454 returned as the status. If the object does not exist, the request 6455 is performed as described for UNCHECKED. 6457 EXCLUSIVE specifies that the server is to follow exclusive creation 6458 semantics, using the verifier to ensure exclusive creation of the 6459 target. The server should check for the presence of a duplicate 6460 object by name. If the object does not exist, the server creates 6461 the object and stores the verifier with the object. If the object 6462 does exist and the stored verifier matches the client provided 6463 verifier, the server uses the existing object as the newly created 6464 object. If the stored verifier does not match, then an error of 6465 NFS4ERR_EXIST is returned. No attributes may be provided in this 6466 case, since the server may use an attribute of the target object to 6467 store the verifier. 6469 For the target directory, the server returns change_info4 6470 information in cinfo. With the atomic field of the change_info4 6471 struct, the server will indicate if the before and after change 6472 attributes were obtained atomically with respect to the link 6473 creation. 6475 Upon successful creation, the current filehandle is replaced by 6476 that of the new object. 6478 The OPEN procedure provides for DOS SHARE capability with the use 6479 of the access and deny fields of the OPEN arguments. The client 6480 specifies at OPEN the required access and deny modes. For clients 6481 that do not directly support SHAREs (i.e. Unix), the expected deny 6482 value is DENY_NONE. In the case that there is a existing SHARE 6483 reservation that conflicts with the OPEN request, the server 6484 returns the error NFS4ERR_DENIED. For a complete SHARE request, 6485 the client must provide values for the owner and seqid fields for 6486 the OPEN argument. For additional discussion of SHARE semantics 6487 see the section on 'Share Reservations'. 6489 In the case that the client is recovering state from a server 6490 failure, the reclaim field of the OPEN argument is used to signify 6491 that the request is meant to reclaim state previously held. 6493 Draft Specification NFS version 4 Protocol February 2000 6495 The "claim" field of the OPEN argument is used to specify the file 6496 to be opened and the state information which the client claims to 6497 possess. There are four basic claim types which cover the various 6498 situations for an OPEN. They are as follows: 6500 CLAIM_NULL 6501 For the client, this is a new OPEN 6502 request and there is no previous state 6503 associate with the file for the client. 6505 CLAIM_PREVIOUS 6506 The client is claiming basic OPEN state 6507 for a file that was held previous to a 6508 server reboot. Generally used when a 6509 server is returning persistent file 6510 handles; the client may not have the 6511 file name to reclaim the OPEN. 6513 CLAIM_DELEGATE_CUR 6514 The client is claiming a delegation for 6515 OPEN as granted by the server. 6516 Generally this is done as part of 6517 recalling a delegation. 6519 CLAIM_DELEGATE_PREV 6520 The client is claiming a delegation 6521 granted to a previous client instance; 6522 used after the client reboots. 6524 For OPEN requests whose claim type is other than CLAIM_PREVIOUS 6525 (i.e. requests other than those devoted to reclaiming opens after a 6526 server reboot) that reach the server during its grace or lease 6527 expiration period, the server returns an error of NFS4ERR_GRACE. 6529 For any OPEN request, the server may return an open delegation, 6530 which allows further opens and closes to be handled locally on the 6531 client as described in the section Open Delegation. Note that 6532 delegation is up to the server to decide. The client should never 6533 assume that delegation will or will not be granted in a particular 6534 instance. It should always be prepared for either case. A partial 6535 exception is the reclaim (CLAIM_PREVIOUS) case, in which a 6536 delegation type is claimed. In this case, delegation will always 6537 be granted, although the server may specify an immediate recall in 6538 the delegation structure. 6540 The rflags returned by a successful OPEN allow the server to return 6541 information governing how the open file is to be handled. 6542 OPEN4_RESULT_MLOCK indicates to the caller that mandatory locking 6543 is in effect for this file and the client should act appropriately 6544 with regard to data cached on the client. OPEN4_RESULT_CONFIRM 6545 indicates that the client MUST execute an OPEN_CONFIRM operation 6547 Draft Specification NFS version 4 Protocol February 2000 6549 before using the open file. 6551 If the file is a zero length array, if any component does not obey 6552 the UTF-8 definition, or if any component in the path is of zero 6553 length, the error NFS4ERR_INVAL will be returned. 6555 When an OPEN is done and the specified lockowner already has the 6556 resulting filehandle open, the result is to "OR" together the new 6557 share and deny status together with the existing status. In this 6558 case, only a single CLOSE need be done, even though multiple OPEN's 6559 were completed. 6561 IMPLEMENTATION 6563 The OPEN procedure contains support for EXCLUSIVE create. The 6564 mechanism is similar to the support in NFS version 3 [RFC1813]. As 6565 in NFS version 3, this mechanism provides reliable exclusive 6566 creation. Exclusive create is invoked when the how parameter is 6567 EXCLUSIVE. In this case, the client provides a verifier that can 6568 reasonably be expected to be unique. A combination of a client 6569 identifier, perhaps the client network address, and a unique number 6570 generated by the client, perhaps the RPC transaction identifier, 6571 may be appropriate. 6573 If the object does not exist, the server creates the object and 6574 stores the verifier in stable storage. For file systems that do not 6575 provide a mechanism for the storage of arbitrary file attributes, 6576 the server may use one or more elements of the object meta-data to 6577 store the verifier. The verifier must be stored in stable storage 6578 to prevent erroneous failure on retransmission of the request. It 6579 is assumed that an exclusive create is being performed because 6580 exclusive semantics are critical to the application. Because of the 6581 expected usage, exclusive CREATE does not rely solely on the 6582 normally volatile duplicate request cache for storage of the 6583 verifier. The duplicate request cache in volatile storage does not 6584 survive a crash and may actually flush on a long network partition, 6585 opening failure windows. In the UNIX local file system 6586 environment, the expected storage location for the verifier on 6587 creation is the meta-data (time stamps) of the object. For this 6588 reason, an exclusive object create may not include initial 6589 attributes because the server would have nowhere to store the 6590 verifier. 6592 If the server can not support these exclusive create semantics, 6593 possibly because of the requirement to commit the verifier to 6594 stable storage, it should fail the OPEN request with the error, 6595 NFS4ERR_NOTSUPP. 6597 Draft Specification NFS version 4 Protocol February 2000 6599 During an exclusive CREATE request, if the object already exists, 6600 the server reconstructs the object's verifier and compares it with 6601 the verifier in the request. If they match, the server treats the 6602 request as a success. The request is presumed to be a duplicate of 6603 an earlier, successful request for which the reply was lost and 6604 that the server duplicate request cache mechanism did not detect. 6605 If the verifiers do not match, the request is rejected with the 6606 status, NFS4ERR_EXIST. 6608 Once the client has performed a successful exclusive create, it 6609 must issue a SETATTR to set the correct object attributes. Until 6610 it does so, it should not rely upon any of the object attributes, 6611 since the server implementation may need to overload object meta- 6612 data to store the verifier. The subsequent SETATTR must not occur 6613 in the same COMPOUND request as the OPEN. This separation will 6614 guarantee that the exclusive create mechanism will continue to 6615 function properly in the face of retransmission of the request. 6617 Use of the GUARDED attribute does not provide exactly-once 6618 semantics. In particular, if a reply is lost and the server does 6619 not detect the retransmission of the request, the procedure can 6620 fail with NFS4ERR_EXIST, even though the create was performed 6621 successfully. 6623 For SHARE reservations, the client must specify a value for access 6624 that is one of READ, WRITE, or BOTH. For deny, the client must 6625 specify one of NONE, READ, WRITE, or BOTH. If the client fails to 6626 do this, the server must return NFS4ERR_INVAL. 6628 ERRORS 6630 NFS4ERR_ACCES 6631 NFS4ERR_BAD_SEQID 6632 NFS4ERR_DELAY 6633 NFS4ERR_DQUOT 6634 NFS4ERR_EXIST 6635 NFS4ERR_FHEXPIRED 6636 NFS4ERR_GRACE 6637 NFS4ERR_IO 6638 NFS4ERR_MOVED 6639 NFS4ERR_NAMETOOLONG 6640 NFS4ERR_NOFILEHANDLE 6641 NFS4ERR_NOSPC 6642 NFS4ERR_NOTDIR 6643 NFS4ERR_NOTSUPP 6644 NFS4ERR_RESOURCE 6645 NFS4ERR_ROFS 6647 Draft Specification NFS version 4 Protocol February 2000 6649 NFS4ERR_SERVERFAULT 6650 NFS4ERR_SHARE_DENIED 6651 NFS4ERR_STALE_CLIENTID 6653 Draft Specification NFS version 4 Protocol February 2000 6655 14.2.17. Operation 19: OPENATTR - Open Named Attribute Directory 6657 SYNOPSIS 6659 (cfh) -> (cfh) 6661 ARGUMENT 6663 /* CURRENT_FH: file or directory */ 6664 void; 6666 RESULT 6668 struct OPENATTR4res { 6669 /* CURRENT_FH: name attr directory*/ 6670 nfsstat4 status; 6671 }; 6673 DESCRIPTION 6675 The OPENATTR operation is used to obtain the filehandle of the 6676 named attribute directory associated with the current filehandle. 6677 The result of the OPENATTR will be a filehandle to an object of 6678 type NF4ATTRDIR. From this filehandle, READDIR and LOOKUP 6679 procedures can be used to obtain filehandles for the various named 6680 attributes associated with the original file system object. 6681 Filehandles returned within the named attribute directory will have 6682 a type of NF4NAMEDATTR. 6684 IMPLEMENTATION 6686 If the server does not support named attributes for the current 6687 filehandle, an error of NFS4ERR_NOTSUPP will be returned to the 6688 client. 6690 ERRORS 6692 NFS4ERR_ACCES 6693 NFS4ERR_BADHANDLE 6694 NFS4ERR_DELAY 6695 NFS4ERR_FHEXPIRED 6696 NFS4ERR_INVAL 6697 NFS4ERR_IO 6699 Draft Specification NFS version 4 Protocol February 2000 6701 NFS4ERR_MOVED 6702 NFS4ERR_NOENT 6703 NFS4ERR_NOFILEHANDLE 6704 NFS4ERR_NOTSUPP 6705 NFS4ERR_RESOURCE 6706 NFS4ERR_SERVERFAULT 6707 NFS4ERR_STALE 6708 NFS4ERR_WRONGSEC 6710 Draft Specification NFS version 4 Protocol February 2000 6712 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open 6714 SYNOPSIS 6716 (cfh), seqid, open_confirm-> stateid 6718 ARGUMENT 6720 struct OPEN_CONFIRM4args { 6721 /* CURRENT_FH: opened file */ 6722 seqid4 seqid; 6723 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 6724 }; 6726 RESULT 6728 struct OPEN_CONFIRM4resok { 6729 stateid4 stateid; 6730 }; 6732 union OPEN_CONFIRM4res switch (nfsstat4 status) { 6733 case NFS4_OK: 6734 OPEN_CONFIRM4resok resok4; 6735 default: 6736 void; 6737 }; 6739 DESCRIPTION 6741 This operation is used to confirm the sequence id usage for the 6742 first time that a nfs_lockowner is used by a client. The OPEN 6743 operation returns a opaque confirmation verifier that is then 6744 passed to this operation along with the next sequence id for the 6745 nfs_lockowner. The sequence id passed to the OPEN_CONFIRM must be 6746 1 (one) greater than the seqid passed to the OPEN operation from 6747 which the open_confirm value was obtained. If the server receives 6748 an unexpected sequence id with respect to the original open, then 6749 the server assumes that the client will not confirm the original 6750 OPEN and all state associated with the original OPEN is released by 6751 the server. 6753 On success, the current filehandle retains its value. 6755 IMPLEMENTATION 6757 Draft Specification NFS version 4 Protocol February 2000 6759 A given client might generate many nfs_lockowner data structures 6760 for a given clientid. The client will periodically either dispose 6761 of its nfs_lockowners or stop using them for indefinite periods of 6762 time. The latter situation is why the NFS version 4 protocol does 6763 not have a an explicit operation to exit an nfs_lockowner: such an 6764 operation is of no use in that situation. Instead, to avoid 6765 unbounded memory use, the server needs to implement a strategy for 6766 disposing of nfs_lockowners that have no current lock, open, or 6767 delegation state for any files and have not been used recently. 6768 The time period used to determine when to dispose of nfs_lockowners 6769 is an implementation choice. The time period should certainly be 6770 no less than the lease time plus any grace period the server wishes 6771 to implement beyond a lease time. The OPEN_CONFIRM operation 6772 allows the server to safely dispose of unused nfs_lockowner data 6773 structures. 6775 In the case that a client issues an OPEN operation and the server 6776 no longer has a record of the nfs_lockowner, the server needs 6777 ensure that this is a new OPEN and not a replay or retransmission. 6779 A lazy server implementation might require confirmation for every 6780 nfs_lockowner for which it has no record. However, this is not 6781 necessary until the server records the fact that it has disposed of 6782 one nfs_lockowner for the given clientid. 6784 The server must hold unconfirmed OPEN state until one of three 6785 events occur. First, the client sends an OPEN_CONFIRM request with 6786 the appropriate sequence id and confirmation verifier within the 6787 lease period. In this case, the OPEN state on the server goes to 6788 confirmed, and the nfs_lockowner on the server is fully 6789 established. 6791 Second, the client sends another OPEN request with a sequence id 6792 that is incorrect for the nfs_lockowner (out of sequence). In this 6793 case, the server assumes the second OPEN request is valid and the 6794 first one is a replay. The server cancels the OPEN state of the 6795 first OPEN requests, establishes an unconfirmed OPEN state for the 6796 second OPEN request, and responds to the second OPEN request with 6797 an indication that an OPEN_CONFIRM is needed. The process then 6798 repeats itself. While there is a potential for a denial of service 6799 attack on the client, it is mitigated if the client and server 6800 require the use of a security flavor based on Kerberos V5, LIPKEY, 6801 or some other flavor that uses cryptography. 6803 What if the server is in the unconfirmed OPEN state for a given 6804 nfs_lockowner, and it receives an operation on the nfs_lockowner 6805 that has a stateid but the operation is not OPEN, or it is 6806 OPEN_CONFIRM but with the wrong confirmation verifier? Then, even 6808 Draft Specification NFS version 4 Protocol February 2000 6810 if the seqid is correct, the server returns NFS4ERR_BAD_STATEID, 6811 because the server assumes the operation is a replay: if the server 6812 has no established OPEN state, then there is no way, for example, a 6813 LOCK operation could be valid. 6815 Third, neither of the two aforementioned events occur for the 6816 nfs_lockowner within the lease period. In this case, the OPEN 6817 state is cancelled and disposal of the nfs_lockowner can occur. 6819 ERRORS 6821 NFS4ERR_BADHANDLE 6822 NFS4ERR_BAD_SEQID 6823 NFS4ERR_EXPIRED 6824 NFS4ERR_FHEXPIRED 6825 NFS4ERR_GRACE 6826 NFS4ERR_INVAL 6827 NFS4ERR_MOVED 6828 NFS4ERR_NOENT 6829 NFS4ERR_NOFILEHANDLE 6830 NFS4ERR_NOTSUPP 6831 NFS4ERR_RESOURCE 6832 NFS4ERR_SERVERFAULT 6833 NFS4ERR_STALE 6834 NFS4ERR_WRONGSEC 6836 Draft Specification NFS version 4 Protocol February 2000 6838 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access 6840 SYNOPSIS 6842 (cfh), stateid, seqid, access, deny -> stateid 6844 ARGUMENT 6846 struct OPEN_DOWNGRADE4args { 6847 /* CURRENT_FH: opened file */ 6848 stateid4 stateid; 6849 seqid4 seqid; 6850 uint32_t share_access; 6851 uint32_t share_deny; 6852 }; 6854 RESULT 6856 struct OPEN_DOWNGRADE4resok { 6857 stateid4 stateid; 6858 }; 6860 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 6861 case NFS4_OK: 6862 OPEN_DOWNGRADE4resok resok4; 6863 default: 6864 void; 6865 }; 6867 This operation is used to adjust the access and deny bits for a given 6868 open. This is necessary when a given lockowner opens the same file 6869 multiple times with different access and deny flags. In this 6870 situation, a close of one of the open's may change the appropriate 6871 access and deny flags to remove bits associated with open's no longer 6872 in effect. 6874 The access and deny bits speicifed in this operation replace the 6875 current ones for the specified open file. If either the access or 6876 the deny mode specified includes bits not in effect for the open, the 6877 error NFS4ERR_INVAL should be returned. Since access and deny bits 6878 are subsets of those already granted, it is is not possible for this 6879 request to denied because of conflicting share reservations. 6881 On success, the current filehandle retains its value. 6883 Draft Specification NFS version 4 Protocol February 2000 6885 ERRORS 6887 NFS4ERR_BADHANDLE 6888 NFS4ERR_BAD_SEQID 6889 NFS4ERR_BAD_STATEID 6890 NFS4ERR_EXPIRED 6891 NFS4ERR_FHEXPIRED 6892 NFS4ERR_INVAL 6893 NFS4ERR_MOVED 6894 NFS4ERR_NOFILEHANDLE 6895 NFS4ERR_OLD_STATEID 6896 NFS4ERR_RESOURCE 6897 NFS4ERR_SERVERFAULT 6898 NFS4ERR_STALE 6899 NFS4ERR_STALE_STATEID 6901 Draft Specification NFS version 4 Protocol February 2000 6903 14.2.20. Operation 22: PUTFH - Set Current Filehandle 6905 SYNOPSIS 6907 filehandle -> (cfh) 6909 ARGUMENT 6911 struct PUTFH4args { 6912 nfs4_fh object; 6913 }; 6915 RESULT 6917 struct PUTFH4res { 6918 /* CURRENT_FH: */ 6919 nfsstat4 status; 6920 }; 6922 DESCRIPTION 6924 Replaces the current filehandle with the filehandle provided as an 6925 argument. 6927 IMPLEMENTATION 6929 Commonly used as the first operator in an NFS request to set the 6930 context for following operations. 6932 ERRORS 6934 NFS4ERR_BADHANDLE 6935 NFS4ERR_FHEXPIRED 6936 NFS4ERR_MOVED 6937 NFS4ERR_RESOURCE 6938 NFS4ERR_SERVERFAULT 6939 NFS4ERR_STALE 6940 NFS4ERR_WRONGSEC 6942 Draft Specification NFS version 4 Protocol February 2000 6944 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle 6946 SYNOPSIS 6948 - -> (cfh) 6950 ARGUMENT 6952 void; 6954 RESULT 6956 struct PUTPUBFH4res { 6957 /* CURRENT_FH: root fh */ 6958 nfsstat4 status; 6959 }; 6961 DESCRIPTION 6963 Replaces the current filehandle with the filehandle that represents 6964 the public filehandle of the server's name space. This filehandle 6965 may be different from the "root" filehandle which may be associated 6966 with some other directory on the server. 6968 IMPLEMENTATION 6970 Used as the first operator in an NFS request to set the context for 6971 following operations. 6973 ERRORS 6975 NFS4ERR_RESOURCE 6976 NFS4ERR_SERVERFAULT 6977 NFS4ERR_WRONGSEC 6979 Draft Specification NFS version 4 Protocol February 2000 6981 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle 6983 SYNOPSIS 6985 - -> (cfh) 6987 ARGUMENT 6989 void; 6991 RESULT 6993 struct PUTROOTFH4res { 6994 /* CURRENT_FH: root fh */ 6995 nfsstat4 status; 6996 }; 6998 DESCRIPTION 7000 Replaces the current filehandle with the filehandle that represents 7001 the root of the server's name space. From this filehandle a LOOKUP 7002 operation can locate any other filehandle on the server. This 7003 filehandle may be different from the "public" filehandle which may 7004 be associated with some other directory on the server. 7006 IMPLEMENTATION 7008 Commonly used as the first operator in an NFS request to set the 7009 context for following operations. 7011 ERRORS 7013 NFS4ERR_RESOURCE 7014 NFS4ERR_SERVERFAULT 7015 NFS4ERR_WRONGSEC 7017 Draft Specification NFS version 4 Protocol February 2000 7019 14.2.23. Operation 25: READ - Read from File 7021 SYNOPSIS 7023 (cfh), offset, count, stateid -> eof, data 7025 ARGUMENT 7027 struct READ4args { 7028 /* CURRENT_FH: file */ 7029 stateid4 stateid; 7030 offset4 offset; 7031 count4 count; 7032 }; 7034 RESULT 7036 struct READ4resok { 7037 bool eof; 7038 opaque data<>; 7039 }; 7041 union READ4res switch (nfsstat4 status) { 7042 case NFS4_OK: 7043 READ4resok resok4; 7044 default: 7045 void; 7046 }; 7048 DESCRIPTION 7050 The READ operation reads data from the regular file identified by 7051 the current filehandle. 7053 The client provides an offset of where the READ is to start and a 7054 count of how many bytes are to be read. An offset of 0 (zero) 7055 means to read data starting at the beginning of the file. If 7056 offset is greater than or equal to the size of the file, the 7057 status, NFS4_OK, is returned with a data length set to 0 (zero) and 7058 eof set to TRUE. The READ is subject to access permissions 7059 checking. 7061 If the client specifies a count value of 0 (zero), the READ 7062 succeeds and returns 0 (zero) bytes of data again subject to access 7063 permissions checking. The server may choose to return fewer bytes 7065 Draft Specification NFS version 4 Protocol February 2000 7067 than specified by the client. The client needs to check for this 7068 condition and handle the condition appropriately. 7070 The stateid value for a READ request represents a value returned 7071 from a previous record lock or share reservation request. Used by 7072 the server to verify that the associated lock is still valid and to 7073 update lease timeouts for the client. 7075 If the read ended at the end-of-file (formally, in a correctly 7076 formed READ request, if offset + count is equal to the size of the 7077 file), eof is returned as TRUE; otherwise it is FALSE. A successful 7078 READ of an empty file will always return eof as TRUE. 7080 IMPLEMENTATION 7082 It is possible for the server to return fewer than count bytes of 7083 data. If the server returns less than the count requested and eof 7084 set to FALSE, the client should issue another READ to get the 7085 remaining data. A server may return less data than requested under 7086 several circumstances. The file may have been truncated by another 7087 client or perhaps on the server itself, changing the file size from 7088 what the requesting client believes to be the case. This would 7089 reduce the actual amount of data available to the client. It is 7090 possible that the server may back off the transfer size and reduce 7091 the read request return. Server resource exhaustion may also occur 7092 necessitating a smaller read return. 7094 If the file is locked the server will return an NFS4ERR_LOCKED 7095 error. Since the lock may be of short duration, the client may 7096 choose to retransmit the READ request (with exponential backoff) 7097 until the operation succeeds. 7099 ERRORS 7101 NFS4ERR_ACCES 7102 NFS4ERR_BADHANDLE 7103 NFS4ERR_BAD_STATEID 7104 NFS4ERR_DELAY 7105 NFS4ERR_DENIED 7106 NFS4ERR_EXPIRED 7107 NFS4ERR_FHEXPIRED 7108 NFS4ERR_GRACE 7109 NFS4ERR_INVAL 7110 NFS4ERR_IO 7111 NFS4ERR_LOCKED 7112 NFS4ERR_MOVED 7114 Draft Specification NFS version 4 Protocol February 2000 7116 NFS4ERR_NOFILEHANDLE 7117 NFS4ERR_NXIO 7118 NFS4ERR_OLD_STATEID 7119 NFS4ERR_RESOURCE 7120 NFS4ERR_SERVERFAULT 7121 NFS4ERR_STALE 7122 NFS4ERR_STALE_STATEID 7123 NFS4ERR_WRONGSEC 7125 Draft Specification NFS version 4 Protocol February 2000 7127 14.2.24. Operation 26: READDIR - Read Directory 7129 SYNOPSIS 7130 (cfh), cookie, cookieverf, dircount, maxcount, attrbits -> 7131 cookieverf { cookie, filename, attrbits, attributes } 7133 ARGUMENT 7135 struct READDIR4args { 7136 /* CURRENT_FH: directory */ 7137 nfs_cookie4 cookie; 7138 verifier4 cookieverf; 7139 count4 dircount; 7140 count4 maxcount; 7141 bitmap4 attr_request; 7142 }; 7144 RESULT 7146 struct entry4 { 7147 nfs_cookie4 cookie; 7148 component4 name; 7149 fattr4 attrs; 7150 entry4 *nextentry; 7151 }; 7153 struct dirlist4 { 7154 entry4 *entries; 7155 bool eof; 7156 }; 7158 struct READDIR4resok { 7159 verifier4 cookieverf; 7160 dirlist4 reply; 7161 }; 7163 union READDIR4res switch (nfsstat4 status) { 7164 case NFS4_OK: 7165 READDIR4resok resok4; 7166 default: 7167 void; 7168 }; 7170 DESCRIPTION 7172 Draft Specification NFS version 4 Protocol February 2000 7174 The READDIR operation retrieves a variable number of entries from a 7175 file system directory and returns client requested attributes for 7176 each entry along with information to allow the client to request 7177 additional directory entries in a subsequent READDIR. 7179 The arguments contain a cookie value that represents where the 7180 READDIR should start within the directory. A value of 0 (zero) for 7181 the cookie is used to start reading at the beginning of the 7182 directory. For subsequent READDIR requests, the client specifies a 7183 cookie value that is provided by the server on a previous READDIR 7184 request. 7186 The cookieverf value should be set to 0 (zero) when the cookie 7187 value is 0 (zero) (first directory read). On subsequent requests, 7188 it should be a cookieverf as returned by the server. The 7189 cookieverf must match that returned by the READDIR in which the 7190 cookie was acquired. 7192 The dircount portion of the argument is a hint of the maximum 7193 number of bytes of directory information that should be returned. 7194 This value is the XDR encoded length of the name of the directory 7195 entries and the cookie value for the entries. The server may 7196 return less data. 7198 The maxcount value of the argument is the maximum number of bytes 7199 for the result. This maximum size represents all of the data being 7200 returned and includes the XDR overhead. The server may return less 7201 data. If the server is unable to return a single directory entry 7202 within the maxcount limit, the error NFS4ERR_READDIR_NOSPC will be 7203 returned to the client. 7205 Finally, attrbits represents the list of attributes to be returned 7206 for each directory entry supplied by the server. 7208 On successful return, the server's response will provide a list of 7209 directory entries. Each of these entries contains the name of the 7210 directory entry, a cookie value for that entry, and the associated 7211 attributes as requested. 7213 The cookie value is only meaningful to the server and is used as a 7214 "bookmark" for the directory entry. As mentioned, this cookie is 7215 used by the client for subsequent READDIR operations so that it may 7216 continue reading a directory. The cookie is similar in concept to 7217 a READ offset but should not be interpreted as such by the client. 7218 Ideally, the cookie value should not change if the directory is 7219 modified. 7221 In some cases, the server may encounter an error while obtaining 7223 Draft Specification NFS version 4 Protocol February 2000 7225 the attributes for a directory entry. Instead of returning an 7226 error for the entire READDIR operation, the server can instead 7227 return the attribute 'fattr4_rdattr_error'. With this, the server 7228 is able to communicate the failure to the client and not fail the 7229 entire operation in the instance of what might be a transient 7230 failure. Obviously, the client must request the 7231 fattr4_rdattr_error attribute for this method to work properly. If 7232 the client does not request the attribute, the server has no choice 7233 but to return failure for the entire READDIR operation. 7235 For some file system environments, the directory entries "." and 7236 ".." have special meaning and in other environments, they may not. 7237 If the server supports these special entries within a directory, 7238 they should not be returned to the client as part of the READDIR 7239 response. To enable some client environments, the cookie values of 7240 0, 1, and 2 are to be considered reserved. For READDIR arguments, 7241 cookie values of 1 and 2 should not be used and for READDIR results 7242 cookie values of 0, 1, and 2 should not returned. 7244 IMPLEMENTATION 7246 The server's file system directory representations can differ 7247 greatly. A client's programming interfaces may also be bound to 7248 the local operating environment in a way that does not translate 7249 well into the NFS protocol. Therefore the use of the dircount and 7250 maxcount fields are provided to allow the client the ability to 7251 provide guidelines to the server. If the client is aggressive 7252 about attribute collection during a READDIR, the server has an idea 7253 of how to limit the encoded response. The dircount field provides 7254 a hint on the number of entries based solely on the names of the 7255 directory entries. Since it is a hint, it may be possible that a 7256 dircount value is zero. In this case, the server is free to ignore 7257 the dircount value and return directory information based on the 7258 specified maxcount value. 7260 The cookieverf may be used by the server to help manage cookie 7261 values that may become stale. It should be a rare occurrence that 7262 a server is unable to continue properly reading a directory with 7263 the provided cookie/cookieverf pair. The server should make every 7264 effort to avoid this condition since the application at the client 7265 may not be able to properly handle this type of failure. 7267 The use of the cookieverf will also protect the client from using 7268 READDIR cookie values that may be stale. For example, if the file 7269 system has been migrated, the server may or may not be able to use 7270 the same cookie values to service READDIR as the previous server 7271 used. With the client providing the cookieverf, the server is able 7273 Draft Specification NFS version 4 Protocol February 2000 7275 to provide the appropriate response to the client. This prevents 7276 the case where the server may accept a cookie value but the 7277 underlying directory has changed and the response is invalid from 7278 the client's context of its previous READDIR. 7280 Since the server will not be returning "." and ".." entries as has 7281 been done with previous versions of the NFS protocol, the client 7282 that requires these entries be present in READDIR responses must 7283 fabricate them. 7285 ERRORS 7287 NFS4ERR_ACCES 7288 NFS4ERR_BADHANDLE 7289 NFS4ERR_BAD_COOKIE 7290 NFS4ERR_DELAY 7291 NFS4ERR_FHEXPIRED 7292 NFS4ERR_INVAL 7293 NFS4ERR_IO 7294 NFS4ERR_MOVED 7295 NFS4ERR_NOFILEHANDLE 7296 NFS4ERR_NOTDIR 7297 NFS4ERR_NOTSUPP 7298 NFS4ERR_READDIR_NOSPC 7299 NFS4ERR_RESOURCE 7300 NFS4ERR_SERVERFAULT 7301 NFS4ERR_STALE 7302 NFS4ERR_TOOSMALL 7303 NFS4ERR_WRONGSEC 7305 Draft Specification NFS version 4 Protocol February 2000 7307 14.2.25. Operation 27: READLINK - Read Symbolic Link 7309 SYNOPSIS 7311 (cfh) -> linktext 7313 ARGUMENT 7315 /* CURRENT_FH: symlink */ 7316 void; 7318 RESULT 7320 struct READLINK4resok { 7321 linktext4 link; 7322 }; 7324 union READLINK4res switch (nfsstat4 status) { 7325 case NFS4_OK: 7326 READLINK4resok resok4; 7327 default: 7328 void; 7329 }; 7331 DESCRIPTION 7333 READLINK reads the data associated with a symbolic link. The data 7334 is a UTF-8 string that is opaque to the server. That is, whether 7335 created by an NFS client or created locally on the server, the data 7336 in a symbolic link is not interpreted when created, but is simply 7337 stored. 7339 IMPLEMENTATION 7341 A symbolic link is nominally a pointer to another file. The data 7342 is not necessarily interpreted by the server, just stored in the 7343 file. It is possible for a client implementation to store a path 7344 name that is not meaningful to the server operating system in a 7345 symbolic link. A READLINK operation returns the data to the client 7346 for interpretation. If different implementations want to share 7347 access to symbolic links, then they must agree on the 7348 interpretation of the data in the symbolic link. 7350 The READLINK operation is only allowed on objects of type, NF4LNK. 7352 Draft Specification NFS version 4 Protocol February 2000 7354 The server should return the error, NFS4ERR_INVAL, if the object is 7355 not of type, NF4LNK. 7357 ERRORS 7359 NFS4ERR_ACCES 7360 NFS4ERR_BADHANDLE 7361 NFS4ERR_DELAY 7362 NFS4ERR_FHEXPIRED 7363 NFS4ERR_INVAL 7364 NFS4ERR_IO 7365 NFS4ERR_MOVED 7366 NFS4ERR_NOFILEHANDLE 7367 NFS4ERR_NOTSUPP 7368 NFS4ERR_RESOURCE 7369 NFS4ERR_SERVERFAULT 7370 NFS4ERR_STALE 7371 NFS4ERR_WRONGSEC 7373 Draft Specification NFS version 4 Protocol February 2000 7375 14.2.26. Operation 28: REMOVE - Remove Filesystem Object 7377 SYNOPSIS 7379 (cfh), filename -> change_info 7381 ARGUMENT 7383 struct REMOVE4args { 7384 /* CURRENT_FH: directory */ 7385 component4 target; 7386 }; 7388 RESULT 7390 struct REMOVE4resok { 7391 change_info4 cinfo; 7392 } 7394 union REMOVE4res switch (nfsstat4 status) { 7395 case NFS4_OK: 7396 REMOVE4resok resok4; 7397 default: 7398 void; 7399 } 7401 DESCRIPTION 7403 The REMOVE operation removes (deletes) a directory entry named by 7404 filename from the directory corresponding to the current 7405 filehandle. If the entry in the directory was the last reference 7406 to the corresponding file system object, the object may be 7407 destroyed. 7409 For the directory where the filename was removed, the server 7410 returns change_info4 information in cinfo. With the atomic field 7411 of the change_info4 struct, the server will indicate if the before 7412 and after change attributes were obtained atomically with respect 7413 to the removal. 7415 If the target has a length of 0 (zero), or if target does not obey 7416 the UTF-8 definition, the error NFS4ERR_INVAL will be returned. 7418 IMPLEMENTATION 7420 Draft Specification NFS version 4 Protocol February 2000 7422 NFS versions 2 and 3 required a different operator RMDIR for 7423 directory removal. NFS version 4 REMOVE can be used to delete any 7424 directory entry independent of its file type. 7426 The concept of last reference is server specific. However, if the 7427 numlinks field in the previous attributes of the object had the 7428 value 1, the client should not rely on referring to the object via 7429 a file handle. Likewise, the client should not rely on the 7430 resources (disk space, directory entry, and so on.) formerly 7431 associated with the object becoming immediately available. Thus, if 7432 a client needs to be able to continue to access a file after using 7433 REMOVE to remove it, the client should take steps to make sure that 7434 the file will still be accessible. The usual mechanism used is to 7435 use RENAME to rename the file from its old name to a new hidden 7436 name. 7438 ERRORS 7440 NFS4ERR_ACCES 7441 NFS4ERR_BADHANDLE 7442 NFS4ERR_DELAY 7443 NFS4ERR_FHEXPIRED 7444 NFS4ERR_IO 7445 NFS4ERR_MOVED 7446 NFS4ERR_NAMETOOLONG 7447 NFS4ERR_NOENT 7448 NFS4ERR_NOFILEHANDLE 7449 NFS4ERR_NOTDIR 7450 NFS4ERR_NOTEMPTY 7451 NFS4ERR_NOTSUPP 7452 NFS4ERR_RESOURCE 7453 NFS4ERR_ROFS 7454 NFS4ERR_SERVERFAULT 7455 NFS4ERR_STALE 7456 NFS4ERR_WRONGSEC 7458 Draft Specification NFS version 4 Protocol February 2000 7460 14.2.27. Operation 29: RENAME - Rename Directory Entry 7462 SYNOPSIS 7464 (sfh), oldname (cfh), newname -> source_change_info, 7465 target_change_info 7467 ARGUMENT 7469 struct RENAME4args { 7470 /* SAVED_FH: source directory */ 7471 component4 oldname; 7472 /* CURRENT_FH: target directory */ 7473 component4 newname; 7474 }; 7476 RESULT 7478 struct RENAME4resok { 7479 change_info4 source_cinfo; 7480 change_info4 target_cinfo; 7481 }; 7483 union RENAME4res switch (nfsstat4 status) { 7484 case NFS4_OK: 7485 RENAME4resok resok4; 7486 default: 7487 void; 7488 }; 7490 DESCRIPTION 7492 The RENAME operation renames the object identified by oldname in 7493 the source directory corresponding to the saved filehandle, as set 7494 by the SAVEFH operation, to newname in the target directory 7495 corresponding to the current filehandle. The operation is required 7496 to be atomic to the client. Source and target directories must 7497 reside on the same file system on the server. On success, the 7498 current filehandle will continue to be the target directory. 7500 If the target directory already contains an entry with the name, 7501 newname, the source object must be compatible with the target: 7502 either both are non-directories or both are directories and the 7503 target must be empty. If compatible, the existing target is 7504 removed before the rename occurs. If they are not compatible or if 7506 Draft Specification NFS version 4 Protocol February 2000 7508 the target is a directory but not empty, the server will return the 7509 error, NFS4ERR_EXIST. 7511 If oldname and newname both refer to the same file (they might be 7512 hard links of each other), then RENAME should perform no action and 7513 return success. 7515 For both directories involved in the RENAME, the server returns 7516 change_info4 information. With the atomic field of the 7517 change_info4 struct, the server will indicate if the before and 7518 after change attributes were obtained atomically with respect to 7519 the rename. 7521 If the oldname or newname has a length of 0 (zero), or if oldname 7522 or newname does not obey the UTF-8 definition, the error 7523 NFS4ERR_INVAL will be returned. 7525 IMPLEMENTATION 7527 The RENAME operation must be atomic to the client. The statement 7528 "source and target directories must reside on the same file system 7529 on the server" means that the fsid fields in the attributes for the 7530 directories are the same. If they reside on different file systems, 7531 the error, NFS4ERR_XDEV, is returned. 7533 A filehandle may or may not become stale or expire on a rename. 7534 However, server implementors are strongly encouraged to attempt to 7535 keep file handles from becoming stale or expiring in this fashion. 7537 On some servers, the filenames, "." and "..", are illegal as either 7538 oldname or newname. In addition, neither oldname nor newname can 7539 be an alias for the source directory. These servers will return 7540 the error, NFS4ERR_INVAL, in these cases. 7542 ERRORS 7544 NFS4ERR_ACCES 7545 NFS4ERR_BADHANDLE 7546 NFS4ERR_DELAY 7547 NFS4ERR_DQUOT 7548 NFS4ERR_EXIST 7549 NFS4ERR_FHEXPIRED 7550 NFS4ERR_INVAL 7551 NFS4ERR_IO 7552 NFS4ERR_ISDIR 7554 Draft Specification NFS version 4 Protocol February 2000 7556 NFS4ERR_MOVED 7557 NFS4ERR_NAMETOOLONG 7558 NFS4ERR_NOENT 7559 NFS4ERR_NOFILEHANDLE 7560 NFS4ERR_NOSPC 7561 NFS4ERR_NOTDIR 7562 NFS4ERR_NOTEMPTY 7563 NFS4ERR_NOTSUPP 7564 NFS4ERR_RESOURCE 7565 NFS4ERR_ROFS 7566 NFS4ERR_SERVERFAULT 7567 NFS4ERR_STALE 7568 NFS4ERR_WRONGSEC 7569 NFS4ERR_XDEV 7571 Draft Specification NFS version 4 Protocol February 2000 7573 14.2.28. Operation 30: RENEW - Renew a Lease 7575 SYNOPSIS 7577 stateid -> () 7579 ARGUMENT 7581 struct RENEW4args { 7582 stateid4 stateid; 7583 }; 7585 RESULT 7587 struct RENEW4res { 7588 nfsstat4 status; 7589 }; 7591 DESCRIPTION 7593 The RENEW operation is used by the client to renew leases which it 7594 currently holds at a server. In processing the RENEW request, the 7595 server renews all leases associated with the client. The 7596 associated leases are determined by the client id provided via the 7597 SETCLIENTID procedure. 7599 The stateid for RENEW may not be one of the special stateids 7600 consisting of all bits 0 (zero) or all bits 1. 7602 IMPLEMENTATION 7604 ERRORS 7606 NFS4ERR_BAD_STATEID 7607 NFS4ERR_EXPIRED 7608 NFS4ERR_GRACE 7609 NFS4ERR_INVAL 7610 NFS4ERR_MOVED 7611 NFS4ERR_OLD_STATEID 7612 NFS4ERR_RESOURCE 7613 NFS4ERR_SERVERFAULT 7614 NFS4ERR_STALE_STATEID 7616 Draft Specification NFS version 4 Protocol February 2000 7618 NFS4ERR_WRONGSEC 7620 Draft Specification NFS version 4 Protocol February 2000 7622 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle 7624 SYNOPSIS 7626 (sfh) -> (cfh) 7628 ARGUMENT 7630 /* SAVED_FH: */ 7631 void; 7633 RESULT 7635 struct RESTOREFH4res { 7636 /* CURRENT_FH: value of saved fh */ 7637 nfsstat4 status; 7638 }; 7640 DESCRIPTION 7642 Set the current filehandle to the value in the saved filehandle. 7643 If there is no saved filehandle then return an error 7644 NFS4ERR_NOFILEHANDLE. 7646 IMPLEMENTATION 7648 Operations like OPEN and LOOKUP use the current filehandle to 7649 represent a directory and replace it with a new filehandle. 7650 Assuming the previous filehandle was saved with a SAVEFH operator, 7651 the previous filehandle can be restored as the current filehandle. 7652 This is commonly used to obtain post-operation attributes for the 7653 directory, e.g. 7655 PUTFH (directory filehandle) 7656 SAVEFH 7657 GETATTR attrbits (pre-op dir attrs) 7658 CREATE optbits "foo" attrs 7659 GETATTR attrbits (file attributes) 7660 RESTOREFH 7661 GETATTR attrbits (post-op dir attrs) 7663 ERRORS 7665 Draft Specification NFS version 4 Protocol February 2000 7667 NFS4ERR_BADHANDLE 7668 NFS4ERR_FHEXPIRED 7669 NFS4ERR_MOVED 7670 NFS4ERR_NOFILEHANDLE 7671 NFS4ERR_RESOURCE 7672 NFS4ERR_SERVERFAULT 7673 NFS4ERR_STALE 7674 NFS4ERR_WRONGSEC 7676 Draft Specification NFS version 4 Protocol February 2000 7678 14.2.30. Operation 32: SAVEFH - Save Current Filehandle 7680 SYNOPSIS 7682 (cfh) -> (sfh) 7684 ARGUMENT 7686 /* CURRENT_FH: */ 7687 void; 7689 RESULT 7691 struct SAVEFH4res { 7692 /* SAVED_FH: value of current fh */ 7693 nfsstat4 status; 7694 }; 7696 DESCRIPTION 7698 Save the current filehandle. If a previous filehandle was saved 7699 then it is no longer accessible. The saved filehandle can be 7700 restored as the current filehandle with the RESTOREFH operator. 7702 On success, the current filehandle retains its value. 7704 IMPLEMENTATION 7706 ERRORS 7708 NFS4ERR_BADHANDLE 7709 NFS4ERR_FHEXPIRED 7710 NFS4ERR_MOVED 7711 NFS4ERR_NOFILEHANDLE 7712 NFS4ERR_RESOURCE 7713 NFS4ERR_SERVERFAULT 7714 NFS4ERR_STALE 7715 NFS4ERR_WRONGSEC 7717 Draft Specification NFS version 4 Protocol February 2000 7719 14.2.31. Operation 33: SECINFO - Obtain Available Security 7721 SYNOPSIS 7723 (cfh), name -> { secinfo } 7725 ARGUMENT 7727 struct SECINFO4args { 7728 /* CURRENT_FH: */ 7729 component4 name; 7730 }; 7732 RESULT 7734 enum rpc_gss_svc_t { 7735 RPC_GSS_SVC_NONE = 1, 7736 RPC_GSS_SVC_INTEGRITY = 2, 7737 RPC_GSS_SVC_PRIVACY = 3 7738 }; 7740 struct rpcsec_gss_info { 7741 sec_oid4 oid; 7742 qop4 qop; 7743 rpc_gss_svc_t service; 7744 }; 7746 struct secinfo4 { 7747 uint32_t flavor; 7748 opaque flavor_info<>; /* null for AUTH_SYS, AUTH_NONE; 7749 contains rpcsec_gss_info for 7750 RPCSEC_GSS. */ 7751 }; 7753 typedef secinfo4 SECINFO4resok<>; 7755 union SECINFO4res switch (nfsstat4 status) { 7756 case NFS4_OK: 7757 SECINFO4resok resok4; 7758 default: 7759 void; 7760 }; 7762 DESCRIPTION 7764 Draft Specification NFS version 4 Protocol February 2000 7766 The SECINFO operation is used by the client to obtain a list of 7767 valid RPC authentication flavors for a specific file handle, file 7768 name pair. The result will contain an array which represents the 7769 security mechanisms available. The array entries are represented 7770 by the secinfo4 structure. The field 'flavor' will contain a value 7771 of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or RPCSEC_GSS (as 7772 defined in [RFC2203]). 7774 For the flavors, AUTH_NONE, and AUTH_SYS no additional security 7775 information is returned. For a return value of RPCSEC_GSS, a 7776 security triple is returned that contains the mechanism object id 7777 (as defined in [RFC2078]), the quality of protection (as defined in 7778 [RFC2078]) and the service type (as defined in [RFC2203]). It is 7779 possible for SECINFO to return multiple entries with flavor equal 7780 to RPCSEC_GSS with different security triple values. 7782 IMPLEMENTATION 7784 The SECINFO operation is expected to be used by the NFS client when 7785 the error value of NFS4ERR_WRONGSEC is returned from another NFS 7786 operation. This signifies to the client that the server's security 7787 policy is different from what the client is currently using. At 7788 this point, the client is expected to obtain a list of possible 7789 security flavors and choose what best suits its policies. 7791 It is recommended that the client issue the SECINFO call protected 7792 by a security triple that uses either rpc_gss_svc_integrity or 7793 rpc_gss_svc_privacy service. The use of rpc_gss_svc_none would 7794 allow an attacker in the middle to modify the SECINFO results such 7795 that the client might select a weaker algorithm in the set allowed 7796 by server, making the client and/or server vulnerable to further 7797 attacks. 7799 ERRORS 7801 NFS4ERR_BADHANDLE 7802 NFS4ERR_FHEXPIRED 7803 NFS4ERR_MOVED 7804 NFS4ERR_NAMETOOLONG 7805 NFS4ERR_NOENT 7806 NFS4ERR_NOFILEHANDLE 7807 NFS4ERR_NOTDIR 7808 NFS4ERR_RESOURCE 7809 NFS4ERR_SERVERFAULT 7810 NFS4ERR_STALE 7811 NFS4ERR_WRONGSEC 7813 Draft Specification NFS version 4 Protocol February 2000 7815 14.2.32. Operation 34: SETATTR - Set Attributes 7817 SYNOPSIS 7819 (cfh), attrbits, attrvals -> - 7821 ARGUMENT 7823 struct SETATTR4args { 7824 /* CURRENT_FH: target object */ 7825 stateid4 stateid; 7826 fattr4 obj_attributes; 7827 }; 7829 RESULT 7831 struct SETATTR4res { 7832 nfsstat4 status; 7833 bitmap4 attrsset; 7834 }; 7836 DESCRIPTION 7838 The SETATTR operation changes one or more of the attributes of a 7839 file system object. The new attributes are specified with a bitmap 7840 and the attributes that follow the bitmap in bit order. 7842 The stateid is necessary for SETATTRs that change the size of file 7843 (modify the attribute object_size). This stateid represents a 7844 record lock, share reservation, or delegation which must be valid 7845 for the SETATTR to modify the file data. A valid stateid would 7846 always be specified. When the file size is not changed, the 7847 special stateid consisting of all bits 0 (zero) should be used. 7849 On either success or failure of the operation, the server will 7850 return the attrsset bitmask to represent what (if any) attributes 7851 were successfully set. 7853 IMPLEMENTATION 7855 The file size attribute is used to request changes to the size of a 7856 file. A value of 0 (zero) causes the file to be truncated, a value 7857 less than the current size of the file causes data from new size to 7858 the end of the file to be discarded, and a size greater than the 7860 Draft Specification NFS version 4 Protocol February 2000 7862 current size of the file causes logically zeroed data bytes to be 7863 added to the end of the file. Servers are free to implement this 7864 using holes or actual zero data bytes. Clients should not make any 7865 assumptions regarding a server's implementation of this feature, 7866 beyond that the bytes returned will be zeroed. Servers must 7867 support extending the file size via SETATTR. 7869 SETATTR is not guaranteed atomic. A failed SETATTR may partially 7870 change a file's attributes. 7872 Changing the size of a file with SETATTR indirectly changes the 7873 time_modify. A client must account for this as size changes can 7874 result in data deletion. 7876 If server and client times differ, programs that compare client 7877 time to file times can break. A time maintenance protocol should be 7878 used to limit client/server time skew. 7880 If the server cannot successfully set all the attributes it must 7881 return an NFS4ERR_INVAL error. If the server can only support 32 7882 bit offsets and sizes, a SETATTR request to set the size of a file 7883 to larger than can be represented in 32 bits will be rejected with 7884 this same error. 7886 ERRORS 7888 NFS4ERR_ACCES 7889 NFS4ERR_BADHANDLE 7890 NFS4ERR_BAD_STATEID 7891 NFS4ERR_DELAY 7892 NFS4ERR_DENIED 7893 NFS4ERR_DQUOT 7894 NFS4ERR_EXPIRED 7895 NFS4ERR_FBIG 7896 NFS4ERR_FHEXPIRED 7897 NFS4ERR_GRACE 7898 NFS4ERR_INVAL 7899 NFS4ERR_IO 7900 NFS4ERR_MOVED 7901 NFS4ERR_NOFILEHANDLE 7902 NFS4ERR_NOSPC 7903 NFS4ERR_NOTSUPP 7904 NFS4ERR_OLD_STATEID 7905 NFS4ERR_PERM 7906 NFS4ERR_RESOURCE 7907 NFS4ERR_ROFS 7908 NFS4ERR_SERVERFAULT 7910 Draft Specification NFS version 4 Protocol February 2000 7912 NFS4ERR_STALE 7913 NFS4ERR_STALE_STATEID 7914 NFS4ERR_WRONGSEC 7916 Draft Specification NFS version 4 Protocol February 2000 7918 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid 7920 SYNOPSIS 7922 client, callback -> clientid, setclientid_confirm 7924 ARGUMENT 7926 struct SETCLIENTID4args { 7927 nfs_client_id4 client; 7928 cb_client4 callback; 7929 }; 7931 RESULT 7933 struct SETCLIENTID4resok { 7934 clientid4 clientid; 7935 verifier4 setclientid_confirm; 7936 }; 7938 union SETCLIENTID4res switch (nfsstat4 status) { 7939 case NFS4_OK: 7940 SETCLIENTID4resok resok4; 7941 case NFS4ERR_CLID_INUSE: 7942 clientaddr4 client_using; 7943 default: 7944 void; 7945 }; 7947 DESCRIPTION 7949 The SETCLIENTID operation introduces the ability of the client to 7950 notify the server of its intention to use a particular client 7951 identifier and verifier pair. Upon successful completion the 7952 server will return a clientid which is used in subsequent file 7953 locking requests and a confirmation verifier. The client will use 7954 the SETCLIENTID_CONFIRM operation to return the verifier to the 7955 server. At that point, the client may use the clientid in 7956 subsequent operations that require an nfs_lockowner. 7958 The callback information provided in this operation will be used if 7959 the client is provided an open delegation at a future point. 7960 Therefore, the client must correctly reflect the program and port 7961 numbers for the callback program at the time SETCLIENTID is used. 7963 Draft Specification NFS version 4 Protocol February 2000 7965 IMPLEMENTATION 7967 The server takes the verifier and client identification supplied in 7968 the nfs_client_id4 and searches for a match of the client 7969 identification. If no match is found the server saves the 7970 principal/uid information along with the verifier and client 7971 identification and returns a unique clientid that is used as a 7972 shorthand reference to the supplied information. 7974 If the server finds matching client identification and a 7975 corresponding match in principal/uid, the server releases all 7976 locking state for the client and returns a new clientid. 7978 The principal or principal to user identifier mapping is taken from 7979 the credential presented in the RPC. As mentioned, the server will 7980 use the credential and associated principal for the matching with 7981 existing clientids. If the client is a traditional host based 7982 client like a Unix NFS client, then the credential presented may be 7983 the host credential. If the client is a user level client or light 7984 weight client, the credential used may be the end user's 7985 credential. The client should take care in choosing an appropriate 7986 credential since denial of service attacks could be attempted by a 7987 rogue client that has access to the credential. 7989 ERRORS 7991 NFS4ERR_CLID_INUSE 7992 NFS4ERR_INVAL 7993 NFS4ERR_RESOURCE 7994 NFS4ERR_SERVERFAULT 7996 Draft Specification NFS version 4 Protocol February 2000 7998 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 8000 SYNOPSIS 8002 setclientid_confirm -> - 8004 ARGUMENT 8006 struct SETCLIENTID_CONFIRM4args { 8007 verifier4 setclientid_confirm; 8008 }; 8010 RESULT 8012 struct SETCLIENTID_CONFIRM4res { 8013 nfsstat4 status; 8014 }; 8016 DESCRIPTION 8018 This operation is used by the client to confirm the results from a 8019 previous call to SETCLIENTID. The client provides the server 8020 supplied (from a SETCLIENTID response) opaque confirmation 8021 verifier. The server responds with a simple status of success or 8022 failure. 8024 IMPLEMENTATION 8026 The client must use the SETCLIENTID_CONFIRM operation to confirm 8027 its use of client identifier. Once the server receives the valid 8028 confirmation, all state previously held by the client (if 8029 applicable) is kept until the receipt of the SETCLIENTID_CONFIRM is 8030 successful. Upon successful confirmation the server will release 8031 the previous state held on behalf of the client. The server should 8032 choose a confirmation cookie value that is reasonably unique for 8033 the client. 8035 ERRORS 8037 NFS4ERR_CLID_INUSE 8038 NFS4ERR_INVAL 8039 NFS4ERR_RESOURCE 8040 NFS4ERR_SERVERFAULT 8042 Draft Specification NFS version 4 Protocol February 2000 8044 NFS4ERR_STALE_CLIENTID 8046 Draft Specification NFS version 4 Protocol February 2000 8048 14.2.35. Operation 37: VERIFY - Verify Same Attributes 8050 SYNOPSIS 8052 (cfh), attrbits, attrvals -> - 8054 ARGUMENT 8056 struct VERIFY4args { 8057 /* CURRENT_FH: object */ 8058 bitmap4 attr_request; 8059 fattr4 obj_attributes; 8060 }; 8062 RESULT 8064 struct VERIFY4res { 8065 nfsstat4 status; 8066 }; 8068 DESCRIPTION 8070 The VERIFY operation is used to verify that attributes have a value 8071 assumed by the client before proceeding with following operations 8072 in the compound request. If any of the attributes do not match 8073 then the error NFS4ERR_NOT_SAME must be returned. The current 8074 filehandle retains its value after successful completion of the 8075 operation. 8077 IMPLEMENTATION 8079 One possible use of the VERIFY operation is the following compound 8080 sequence. With this the client is attempting to verify that the 8081 file being removed will match what the client expects to be 8082 removed. This sequence can help prevent the unintended deletion of 8083 a file. 8085 PUTFH (directory filehandle) 8086 LOOKUP (file name) 8087 VERIFY (filehandle == fh) 8088 PUTFH (directory filehandle) 8089 REMOVE (file name) 8091 This sequence does not prevent a second client from removing and 8092 creating a new file in the middle of this sequence but it does help 8094 Draft Specification NFS version 4 Protocol February 2000 8096 avoid the unintended result. 8098 In the case that a recommended attribute is specified in the VERIFY 8099 operation and the server does not support that attribute for the 8100 file system object, the error NFS4ERR_NOTSUPP is returned to the 8101 client. 8103 ERRORS 8105 NFS4ERR_ACCES 8106 NFS4ERR_BADHANDLE 8107 NFS4ERR_DELAY 8108 NFS4ERR_FHEXPIRED 8109 NFS4ERR_INVAL 8110 NFS4ERR_MOVED 8111 NFS4ERR_NOFILEHANDLE 8112 NFS4ERR_NOTSUPP 8113 NFS4ERR_NOT_SAME 8114 NFS4ERR_RESOURCE 8115 NFS4ERR_SERVERFAULT 8116 NFS4ERR_STALE 8117 NFS4ERR_WRONGSEC 8119 Draft Specification NFS version 4 Protocol February 2000 8121 14.2.36. Operation 38: WRITE - Write to File 8123 SYNOPSIS 8125 (cfh), offset, count, stability, stateid, data -> count, committed, 8126 verifier 8128 ARGUMENT 8130 enum stable_how4 { 8131 UNSTABLE4 = 0, 8132 DATA_SYNC4 = 1, 8133 FILE_SYNC4 = 2 8134 }; 8136 struct WRITE4args { 8137 /* CURRENT_FH: file */ 8138 stateid4 stateid; 8139 offset4 offset; 8140 stable_how4 stable; 8141 opaque data<>; 8142 }; 8144 RESULT 8146 struct WRITE4resok { 8147 count4 count; 8148 stable_how4 committed; 8149 verifier4writeverf; 8150 }; 8152 union WRITE4res switch (nfsstat4 status) { 8153 case NFS4_OK: 8154 WRITE4resok resok4; 8155 default: 8156 void; 8157 }; 8159 DESCRIPTION 8161 The WRITE operation is used to write data to a regular file. The 8162 target file is specified by the current filehandle. The offset 8163 specifies the offset where the data should be written. An offset 8164 of 0 (zero) specifies that the write should start at the beginning 8165 of the file. The count represents the number of bytes of data that 8167 Draft Specification NFS version 4 Protocol February 2000 8169 are to be written. If the count is 0 (zero), the WRITE will 8170 succeed and return a count of 0 (zero) subject to permissions 8171 checking. The server may choose to write fewer bytes than 8172 requested by the client. 8174 Part of the write request is a specification of how the write is to 8175 be performed. The client specifies with the stable parameter the 8176 method of how the data is to be processed by the server. If stable 8177 is FILE_SYNC4, the server must commit the data written plus all 8178 file system metadata to stable storage before returning results. 8179 This corresponds to the NFS version 2 protocol semantics. Any 8180 other behavior constitutes a protocol violation. If stable is 8181 DATA_SYNC4, then the server must commit all of the data to stable 8182 storage and enough of the metadata to retrieve the data before 8183 returning. The server implementor is free to implement DATA_SYNC4 8184 in the same fashion as FILE_SYNC4, but with a possible performance 8185 drop. If stable is UNSTABLE4, the server is free to commit any 8186 part of the data and the metadata to stable storage, including all 8187 or none, before returning a reply to the client. There is no 8188 guarantee whether or when any uncommitted data will subsequently be 8189 committed to stable storage. The only guarantees made by the server 8190 are that it will not destroy any data without changing the value of 8191 verf and that it will not commit the data and metadata at a level 8192 less than that requested by the client. 8194 The stateid returned from a previous record lock or share 8195 reservation request is provided as part of the argument. The 8196 stateid is used by the server to verify that the associated lock is 8197 still valid and to update lease timeouts for the client. 8199 Upon successful completion, the following results are returned. 8200 The count result is the number of bytes of data written to the 8201 file. The server may write fewer bytes than requested. If so, the 8202 actual number of bytes written starting at location, offset, is 8203 returned. 8205 The server also returns an indication of the level of commitment of 8206 the data and metadata via committed. If the server committed all 8207 data and metadata to stable storage, committed should be set to 8208 FILE_SYNC4. If the level of commitment was at least as strong as 8209 DATA_SYNC4, then committed should be set to DATA_SYNC4. Otherwise, 8210 committed must be returned as UNSTABLE4. If stable was FILE4_SYNC, 8211 then committed must also be FILE_SYNC4: anything else constitutes a 8212 protocol violation. If stable was DATA_SYNC4, then committed may be 8213 FILE_SYNC4 or DATA_SYNC4: anything else constitutes a protocol 8214 violation. If stable was UNSTABLE4, then committed may be either 8215 FILE_SYNC4, DATA_SYNC4, or UNSTABLE4. 8217 Draft Specification NFS version 4 Protocol February 2000 8219 The final portion of the result is the write verifier, verf. The 8220 write verifier is a cookie that the client can use to determine 8221 whether the server has changed state between a call to WRITE and a 8222 subsequent call to either WRITE or COMMIT. This cookie must be 8223 consistent during a single instance of the NFS version 4 protocol 8224 service and must be unique between instances of the NFS version 4 8225 protocol server, where uncommitted data may be lost. 8227 If a client writes data to the server with the stable argument set 8228 to UNSTABLE4 and the reply yields a committed response of 8229 DATA_SYNC4 or UNSTABLE4, the client will follow up some time in the 8230 future with a COMMIT operation to synchronize outstanding 8231 asynchronous data and metadata with the server's stable storage, 8232 barring client error. It is possible that due to client crash or 8233 other error that a subsequent COMMIT will not be received by the 8234 server. 8236 On success, the current filehandle retains its value. 8238 IMPLEMENTATION 8240 It is possible for the server to write fewer than count bytes of 8241 data. In this case, the server should not return an error unless 8242 no data was written at all. If the server writes less than count 8243 bytes, the client should issue another WRITE to write the remaining 8244 data. 8246 It is assumed that the act of writing data to a file will cause the 8247 time_modified of the file to be updated. However, the 8248 time_modified of the file should not be changed unless the contents 8249 of the file are changed. Thus, a WRITE request with count set to 0 8250 should not cause the time_modified of the file to be updated. 8252 The definition of stable storage has been historically a point of 8253 contention. The following expected properties of stable storage 8254 may help in resolving design issues in the implementation. Stable 8255 storage is persistent storage that survives: 8257 1. Repeated power failures. 8258 2. Hardware failures (of any board, power supply, etc.). 8259 3. Repeated software crashes, including reboot cycle. 8261 This definition does not address failure of the stable storage 8262 module itself. 8264 Draft Specification NFS version 4 Protocol February 2000 8266 The verifier is defined to allow a client to detect different 8267 instances of an NFS version 4 protocol server over which cached, 8268 uncommitted data may be lost. In the most likely case, the verifier 8269 allows the client to detect server reboots. This information is 8270 required so that the client can safely determine whether the server 8271 could have lost cached data. If the server fails unexpectedly and 8272 the client has uncommitted data from previous WRITE requests (done 8273 with the stable argument set to UNSTABLE4 and in which the result 8274 committed was returned as UNSTABLE4 as well) it may not have 8275 flushed cached data to stable storage. The burden of recovery is on 8276 the client and the client will need to retransmit the data to the 8277 server. 8279 A suggested verifier would be to use the time that the server was 8280 booted or the time the server was last started (if restarting the 8281 server without a reboot results in lost buffers). 8283 The committed field in the results allows the client to do more 8284 effective caching. If the server is committing all WRITE requests 8285 to stable storage, then it should return with committed set to 8286 FILE_SYNC4, regardless of the value of the stable field in the 8287 arguments. A server that uses an NVRAM accelerator may choose to 8288 implement this policy. The client can use this to increase the 8289 effectiveness of the cache by discarding cached data that has 8290 already been committed on the server. 8292 Some implementations may return NFS4ERR_NOSPC instead of 8293 NFS4ERR_DQUOT when a user's quota is exceeded. 8295 ERRORS 8297 NFS4ERR_ACCES 8298 NFS4ERR_BADHANDLE 8299 NFS4ERR_BAD_STATEID 8300 NFS4ERR_DELAY 8301 NFS4ERR_DENIED 8302 NFS4ERR_DQUOT 8303 NFS4ERR_EXPIRED 8304 NFS4ERR_FBIG 8305 NFS4ERR_FHEXPIRED 8306 NFS4ERR_GRACE 8307 NFS4ERR_INVAL 8308 NFS4ERR_IO 8309 NFS4ERR_LOCKED 8310 NFS4ERR_MOVED 8311 NFS4ERR_NOFILEHANDLE 8312 NFS4ERR_NOSPC 8314 Draft Specification NFS version 4 Protocol February 2000 8316 NFS4ERR_OLD_STATEID 8317 NFS4ERR_RESOURCE 8318 NFS4ERR_ROFS 8319 NFS4ERR_SERVERFAULT 8320 NFS4ERR_STALE 8321 NFS4ERR_STALE_STATEID 8322 NFS4ERR_WRONGSEC 8324 Draft Specification NFS version 4 Protocol February 2000 8326 15. NFS Version 4 Callback Procedures 8328 The procedures used for callbacks are defined in the following 8329 sections. In the interest of clarity, the terms "client" and 8330 "server" refer to NFS clients and servers, despite the fact that for 8331 an individual callback RPC, the sense of these terms would be 8332 precisely the opposite. 8334 15.1. Procedure 0: CB_NULL - No Operation 8336 SYNOPSIS 8338 8340 ARGUMENT 8342 void; 8344 RESULT 8346 void; 8348 DESCRIPTION 8350 Standard NULL procedure. Void argument, void response. This 8351 procedure has no functionality associated with it. 8353 ERRORS 8355 None. 8357 Draft Specification NFS version 4 Protocol February 2000 8359 15.2. Procedure 1: CB_COMPOUND - Compound Operations 8361 SYNOPSIS 8363 compoundargs -> compoundres 8365 ARGUMENT 8367 enum nfs_cb_opnum4 { 8368 OP_CB_GETATTR = 3, 8369 OP_CB_RECALL = 4 8370 }; 8372 union nfs_cb_argop4 switch (unsigned argop) { 8373 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 8374 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 8375 }; 8377 struct CB_COMPOUND4args { 8378 utf8string tag; 8379 uint32_t minorversion; 8380 nfs_cb_argop4 argarray<>; 8381 }; 8383 RESULT 8385 union nfs_cb_resop4 switch (unsigned resop){ 8386 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 8387 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 8388 }; 8390 struct CB_COMPOUND4args { 8391 utf8string tag; 8392 uint32_t minorversion; 8393 nfs_cb_argop4 argarray<>; 8394 }; 8396 struct CB_COMPOUND4res { 8397 nfsstat4 status; 8398 utf8string tag; 8399 nfs_cb_resop4 resarray<>; 8400 }; 8402 DESCRIPTION 8404 Draft Specification NFS version 4 Protocol February 2000 8406 The CB_COMPOUND procedure is used to combine one or more of the 8407 callback procedures into a single RPC request. The main callback 8408 RPC program has two main procedures: CB_NULL and CB_COMPOUND. All 8409 other operations use the CB_COMPOUND procedure as a wrapper. 8411 In the processing of the CB_COMPOUND procedure, the client may find 8412 that it does not have the available resources to execute any or all 8413 of the operations within the CB_COMPOUND sequence. In this case, 8414 the error NFS4ERR_RESOURCE will be returned for the particular 8415 operation within the CB_COMPOUND procedure where the resource 8416 exhaustion occurred. This assumes that all previous operations 8417 within the CB_COMPOUND sequence have been evaluated successfully. 8419 Contained within the CB_COMPOUND results is a 'status' field. This 8420 status must be equivalent to the status of the last operation that 8421 was executed within the CB_COMPOUND procedure. Therefore, if an 8422 operation incurred an error then the 'status' value will be the 8423 same error value as is being returned for the operation that 8424 failed. 8426 IMPLEMENTATION 8428 The CB_COMPOUND procedure is used to combine individual operations 8429 into a single RPC request. The client interprets each of the 8430 operations in turn. If an operation is executed by the client and 8431 the status of that operation is NFS4_OK, then the next operation in 8432 the CB_COMPOUND procedure is executed. The client continues this 8433 process until there are no more operations to be executed or one of 8434 the operations has a status value other than NFS4_OK. 8436 ERRORS 8438 All errors defined in the protocol 8440 Draft Specification NFS version 4 Protocol February 2000 8442 15.2.1. Operation 3: CB_GETATTR - Get Attributes 8444 SYNOPSIS 8446 fh, attrbits -> attrbits, attrvals 8448 ARGUMENT 8450 struct CB_GETATTR4args { 8451 nfs_fh4 fh; 8452 bitmap4 attr_request; 8453 }; 8455 RESULT 8457 struct CB_GETATTR4resok { 8458 fattr4 obj_attributes; 8459 }; 8461 union CB_GETATTR4res switch (nfsstat4 status) { 8462 case NFS4_OK: 8463 CB_GETATTR4resok resok4; 8464 default: 8465 void; 8466 }; 8468 DESCRIPTION 8470 The CB_GETATTR operation is used to obtain the attributes modified 8471 by an open delegate to allow the server to respond to GETATTR 8472 requests for a file which is the subject of an open delegation. 8474 If the handle specified is not one for which the client holds a 8475 write open delegation, an NFS4ERR_BADHANDLE error is returned. 8477 IMPLEMENTATION 8479 The client returns attrbits and the associated attribute values 8480 only for attributes that it may change (change, time_modify, 8481 object_size). It may further limit the response to attributes that 8482 it has in fact changed during the scope of the delegation. 8484 Draft Specification NFS version 4 Protocol February 2000 8486 ERRORS 8488 NFS4ERR_BADHANDLE 8489 NFS4ERR_RESOURCE 8491 Draft Specification NFS version 4 Protocol February 2000 8493 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation 8495 SYNOPSIS 8497 stateid, truncate, fh -> status 8499 ARGUMENT 8501 struct CB_RECALL4args { 8502 stateid4 stateid; 8503 bool truncate; 8504 nfs_fh4 fh; 8505 }; 8507 RESULT 8509 struct CB_RECALL4res { 8510 nfsstat4 status; 8511 }; 8513 DESCRIPTION 8515 The CB_RECALL operation is used to begin the process of recalling 8516 an open delegation and returning it to the server. 8518 The truncate flag is used to optimize recall for a file which is 8519 about to be truncated to zero. When it is set, the client is freed 8520 of obligation to propagate modified data for the file to the 8521 server, since this data is irrelevant. 8523 If the handle specified is not one for which the client holds an 8524 open delegation, an NFS4ERR_BADHANDLE error is returned. 8526 If the stateid specified is not one corresponding to an open 8527 delegation for the file specified by the filehandle, an 8528 NFS4ERR_BAD_STATEID is returned. 8530 IMPLEMENTATION 8532 The client should reply to the callback immediately. Replying does 8533 not complete the recall. The recall is not complete until the 8534 delegation is returned using a DELEGRETURN. 8536 Draft Specification NFS version 4 Protocol February 2000 8538 ERRORS 8540 NFS4ERR_BADHANDLE 8541 NFS4ERR_BAD_STATEID 8542 NFS4ERR_RESOURCE 8544 Draft Specification NFS version 4 Protocol February 2000 8546 16. Security Considerations 8548 The major security feature to consider is the authentication of the 8549 user making the request of NFS service. Consideration should also be 8550 given to the integrity and privacy of this NFS request. These 8551 specific issues are discussed as part of the section on "RPC and 8552 Security Flavor". 8554 Draft Specification NFS version 4 Protocol February 2000 8556 17. IANA Considerations 8558 17.1. Named Attribute Definition 8560 The NFS version 4 protocol provides for the association of named 8561 attributes to files. The name space identifiers for these attributes 8562 are defined as string names. The protocol does not define the 8563 specific assignment of the name space for these file attributes; the 8564 application developer or system vendor is allowed to define the 8565 attribute, its semantics, and the associated name. Even though this 8566 name space will not be specifically controlled to prevent collisions, 8567 the application developer or system vendor is strongly encouraged to 8568 provide the name assignment and associated semantics for attributes 8569 via an information RFC. This will provide for interoperability where 8570 common interests exist. 8572 Draft Specification NFS version 4 Protocol February 2000 8574 18. RPC definition file 8576 /* 8577 * Copyright (C) The Internet Society (1998,2000). 8578 * All Rights Reserved. 8579 */ 8581 /* 8582 * nfs4_prot.x 8583 * 8584 */ 8586 %#pragma ident "@(#)nfs4_prot.x 1.90 00/02/07" 8588 /* 8589 * Basic typedefs for RFC 1832 data type definitions 8590 */ 8591 typedef int int32_t; 8592 typedef unsigned int uint32_t; 8593 typedef hyper int64_t; 8594 typedef unsigned hyper uint64_t; 8596 /* 8597 * Sizes 8598 */ 8599 const NFS4_FHSIZE = 128; 8600 const NFS4_VERIFIER_SIZE = 8; 8602 /* 8603 * File types 8604 */ 8605 enum nfs_ftype4 { 8606 NF4REG = 1, /* Regular File */ 8607 NF4DIR = 2, /* Directory */ 8608 NF4BLK = 3, /* Special File - block device */ 8609 NF4CHR = 4, /* Special File - character device */ 8610 NF4LNK = 5, /* Symbolic Link */ 8611 NF4SOCK = 6, /* Special File - socket */ 8612 NF4FIFO = 7, /* Special File - fifo */ 8613 NF4ATTRDIR = 8, /* Attribute Directory */ 8614 NF4NAMEDATTR = 9 /* Named Attribute */ 8615 }; 8617 /* 8618 * Error status 8619 */ 8620 enum nfsstat4 { 8621 NFS4_OK = 0, 8623 Draft Specification NFS version 4 Protocol February 2000 8625 NFS4ERR_PERM = 1, 8626 NFS4ERR_NOENT = 2, 8627 NFS4ERR_IO = 5, 8628 NFS4ERR_NXIO = 6, 8629 NFS4ERR_ACCES = 13, 8630 NFS4ERR_EXIST = 17, 8631 NFS4ERR_XDEV = 18, 8632 NFS4ERR_NODEV = 19, 8633 NFS4ERR_NOTDIR = 20, 8634 NFS4ERR_ISDIR = 21, 8635 NFS4ERR_INVAL = 22, 8636 NFS4ERR_FBIG = 27, 8637 NFS4ERR_NOSPC = 28, 8638 NFS4ERR_ROFS = 30, 8639 NFS4ERR_MLINK = 31, 8640 NFS4ERR_NAMETOOLONG = 63, 8641 NFS4ERR_NOTEMPTY = 66, 8642 NFS4ERR_DQUOT = 69, 8643 NFS4ERR_STALE = 70, 8644 NFS4ERR_BADHANDLE = 10001, 8645 NFS4ERR_NOT_SYNC = 10002, 8646 NFS4ERR_BAD_COOKIE = 10003, 8647 NFS4ERR_NOTSUPP = 10004, 8648 NFS4ERR_TOOSMALL = 10005, 8649 NFS4ERR_SERVERFAULT = 10006, 8650 NFS4ERR_BADTYPE = 10007, 8651 NFS4ERR_DELAY = 10008, 8652 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 8653 NFS4ERR_DENIED = 10010,/* lock unavailable */ 8654 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 8655 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 8656 NFS4ERR_GRACE = 10013,/* in grace period */ 8657 NFS4ERR_FHEXPIRED = 10014,/* file handle expired */ 8658 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 8659 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 8660 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 8661 NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ 8662 NFS4ERR_MOVED = 10019,/* filesystem relocated */ 8663 NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */ 8664 NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */ 8665 NFS4ERR_STALE_CLIENTID = 10022, 8666 NFS4ERR_STALE_STATEID = 10023, 8667 NFS4ERR_OLD_STATEID = 10024, 8668 NFS4ERR_BAD_STATEID = 10025, 8669 NFS4ERR_BAD_SEQID = 10026, 8670 NFS4ERR_NOT_SAME = 10027,/* verify - attrs not same */ 8671 NFS4ERR_LOCK_RANGE = 10028, 8672 NFS4ERR_SYMLINK = 10029, 8674 Draft Specification NFS version 4 Protocol February 2000 8676 NFS4ERR_READDIR_NOSPC = 10030 8677 }; 8679 /* 8680 * Basic data types 8681 */ 8682 typedef uint32_t bitmap4<>; 8683 typedef uint64_t offset4; 8684 typedef uint32_t count4; 8685 typedef uint64_t length4; 8686 typedef uint64_t clientid4; 8687 typedef uint64_t stateid4; 8688 typedef uint32_t seqid4; 8689 typedef opaque utf8string<>; 8690 typedef utf8string component4; 8691 typedef component4 pathname4<>; 8692 typedef uint64_t nfs_lockid4; 8693 typedef uint64_t nfs_cookie4; 8694 typedef utf8string linktext4; 8695 typedef opaque sec_oid4<>; 8696 typedef uint32_t qop4; 8697 typedef uint32_t mode4; 8698 typedef uint64_t changeid4; 8699 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 8701 /* 8702 * Timeval 8703 */ 8704 struct nfstime4 { 8705 int64_t seconds; 8706 uint32_t nseconds; 8707 }; 8709 enum time_how4 { 8710 SET_TO_SERVER_TIME4 = 0, 8711 SET_TO_CLIENT_TIME4 = 1 8712 }; 8714 union settime4 switch (time_how4 set_it) { 8715 case SET_TO_CLIENT_TIME4: 8716 nfstime4 time; 8717 default: 8718 void; 8719 }; 8721 /* 8722 * File access handle 8723 */ 8725 Draft Specification NFS version 4 Protocol February 2000 8727 typedef opaque nfs_fh4; 8729 /* 8730 * File attribute definitions 8731 */ 8733 /* 8734 * FSID structure for major/minor 8735 */ 8736 struct fsid4 { 8737 uint64_t major; 8738 uint64_t minor; 8739 }; 8741 /* 8742 * Filesystem locations attribute for relocation/migration 8743 */ 8744 struct fs_location4 { 8745 utf8string server<>; 8746 pathname4 rootpath; 8747 }; 8749 struct fs_locations4 { 8750 pathname4 fs_root; 8751 fs_location4 locations<>; 8752 }; 8754 /* 8755 * Various Access Control Entry definitions 8756 */ 8758 /* 8759 * Mask that indicates which Access Control Entries are supported. 8760 * Values for the fattr4_aclsupport attribute. 8761 */ 8762 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 8763 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 8764 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 8765 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 8767 typedef uint32_t acetype4; 8769 /* 8770 * acetype4 values, others can be added as needed. 8771 */ 8772 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 8774 Draft Specification NFS version 4 Protocol February 2000 8776 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 8777 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 8778 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 8780 /* 8781 * ACE flag 8782 */ 8783 typedef uint32_t aceflag4; 8785 /* 8786 * ACE flag values 8787 */ 8788 const ACE4_FILE_INHERIT_ACE = 0x00000001; 8789 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 8790 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 8791 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 8792 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 8793 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 8794 const ACE4_IDENTIFIER_GROUP = 0x00000040; 8796 /* 8797 * ACE mask 8798 */ 8799 typedef uint32_t acemask4; 8801 /* 8802 * ACE mask values 8803 */ 8804 const ACE4_READ_DATA = 0x00000001; 8805 const ACE4_LIST_DIRECTORY = 0x00000001; 8806 const ACE4_WRITE_DATA = 0x00000002; 8807 const ACE4_ADD_FILE = 0x00000002; 8808 const ACE4_APPEND_DATA = 0x00000004; 8809 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 8810 const ACE4_READ_NAMED_ATTRS = 0x00000008; 8811 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 8812 const ACE4_EXECUTE = 0x00000020; 8813 const ACE4_DELETE_CHILD = 0x00000040; 8814 const ACE4_READ_ATTRIBUTES = 0x00000080; 8815 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 8817 const ACE4_DELETE = 0x00010000; 8818 const ACE4_READ_ACL = 0x00020000; 8819 const ACE4_WRITE_ACL = 0x00040000; 8820 const ACE4_WRITE_OWNER = 0x00080000; 8821 const ACE4_SYNCHRONIZE = 0x00100000; 8823 Draft Specification NFS version 4 Protocol February 2000 8825 /* 8826 * ACE4_GENERIC_READ -- defined as combination of 8827 * ACE4_READ_ACL | 8828 * ACE4_READ_DATA | 8829 * ACE4_READ_ATTRIBUTES | 8830 * ACE4_SYNCHRONIZE 8831 */ 8833 const ACE4_GENERIC_READ = 0x00120081; 8835 /* 8836 * ACE4_GENERIC_WRITE -- defined as combination of 8837 * ACE4_READ_ACL | 8838 * ACE4_WRITE_DATA | 8839 * ACE4_WRITE_ATTRIBUTES | 8840 * ACE4_WRITE_ACL | 8841 * ACE4_APPEND_DATA | 8842 * ACE4_SYNCHRONIZE 8843 */ 8844 const ACE4_GENERIC_WRITE = 0x00160102; 8846 /* 8847 * ACE4_GENERIC_EXECUTE -- defined as combination of 8848 * ACE4_READ_ACL 8849 * ACE4_READ_ATTRIBUTES 8850 * ACE4_EXECUTE 8851 * ACE4_SYNCHRONIZE 8852 */ 8853 const ACE4_GENERIC_EXECUTE = 0x001200A0; 8855 /* 8856 * Access Control Entry definition 8857 */ 8858 struct nfsace4 { 8859 acetype4 type; 8860 aceflag4 flag; 8861 acemask4 access_mask; 8862 utf8string who; 8863 }; 8865 /* 8866 * Special data/attribute associated with 8867 * file types NF4BLK and NF4CHR. 8868 */ 8869 struct specdata4 { 8870 uint32_t specdata1; 8872 Draft Specification NFS version 4 Protocol February 2000 8874 uint32_t specdata2; 8875 }; 8877 /* 8878 * Values for fattr4_fh_expire_type 8879 */ 8880 const FH4_PERSISTENT = 0x00000000; 8881 const FH4_NOEXPIRE_WITH_OPEN = 0x00000001; 8882 const FH4_VOLATILE_ANY = 0x00000002; 8883 const FH4_VOL_MIGRATION = 0x00000004; 8884 const FH4_VOL_RENAME = 0x00000008; 8886 typedef bitmap4 fattr4_supported_attrs; 8887 typedef nfs_ftype4 fattr4_type; 8888 typedef uint32_t fattr4_fh_expire_type; 8889 typedef changeid4 fattr4_change; 8890 typedef uint64_t fattr4_size; 8891 typedef bool fattr4_link_support; 8892 typedef bool fattr4_symlink_support; 8893 typedef bool fattr4_named_attr; 8894 typedef fsid4 fattr4_fsid; 8895 typedef bool fattr4_unique_handles; 8896 typedef uint32_t fattr4_lease_time; 8897 typedef nfsstat4 fattr4_rdattr_error; 8899 typedef nfsace4 fattr4_acl<>; 8900 typedef uint32_t fattr4_aclsupport; 8901 typedef bool fattr4_archive; 8902 typedef bool fattr4_cansettime; 8903 typedef bool fattr4_case_insensitive; 8904 typedef bool fattr4_case_preserving; 8905 typedef bool fattr4_chown_restricted; 8906 typedef uint64_t fattr4_fileid; 8907 typedef uint64_t fattr4_files_avail; 8908 typedef nfs_fh4 fattr4_filehandle; 8909 typedef uint64_t fattr4_files_free; 8910 typedef uint64_t fattr4_files_total; 8911 typedef fs_locations4 fattr4_fs_locations; 8912 typedef bool fattr4_hidden; 8913 typedef bool fattr4_homogeneous; 8914 typedef uint64_t fattr4_maxfilesize; 8915 typedef uint32_t fattr4_maxlink; 8916 typedef uint32_t fattr4_maxname; 8917 typedef uint64_t fattr4_maxread; 8918 typedef uint64_t fattr4_maxwrite; 8919 typedef utf8string fattr4_mimetype; 8920 typedef mode4 fattr4_mode; 8922 Draft Specification NFS version 4 Protocol February 2000 8924 typedef bool fattr4_no_trunc; 8925 typedef uint32_t fattr4_numlinks; 8926 typedef utf8string fattr4_owner; 8927 typedef utf8string fattr4_owner_group; 8928 typedef uint64_t fattr4_quota_hard; 8929 typedef uint64_t fattr4_quota_soft; 8930 typedef uint64_t fattr4_quota_used; 8931 typedef specdata4 fattr4_rawdev; 8932 typedef uint64_t fattr4_space_avail; 8933 typedef uint64_t fattr4_space_free; 8934 typedef uint64_t fattr4_space_total; 8935 typedef uint64_t fattr4_space_used; 8936 typedef bool fattr4_system; 8937 typedef nfstime4 fattr4_time_access; 8938 typedef settime4 fattr4_time_access_set; 8939 typedef nfstime4 fattr4_time_backup; 8940 typedef nfstime4 fattr4_time_create; 8941 typedef nfstime4 fattr4_time_delta; 8942 typedef nfstime4 fattr4_time_metadata; 8943 typedef nfstime4 fattr4_time_modify; 8944 typedef settime4 fattr4_time_modify_set; 8946 /* 8947 * Mandatory Attributes 8948 */ 8949 const FATTR4_SUPPORTED_ATTRS = 0; 8950 const FATTR4_TYPE = 1; 8951 const FATTR4_PERSISTENT_FH = 2; 8952 const FATTR4_CHANGE = 3; 8953 const FATTR4_SIZE = 4; 8954 const FATTR4_LINK_SUPPORT = 5; 8955 const FATTR4_SYMLINK_SUPPORT = 6; 8956 const FATTR4_NAMED_ATTR = 7; 8957 const FATTR4_FSID = 8; 8958 const FATTR4_UNIQUE_HANDLES = 9; 8959 const FATTR4_LEASE_TIME = 10; 8960 const FATTR4_RDATTR_ERROR = 11; 8962 /* 8963 * Recommended Attributes 8964 */ 8965 const FATTR4_ACL = 12; 8966 const FATTR4_ACLSUPPORT = 13; 8967 const FATTR4_ARCHIVE = 14; 8968 const FATTR4_CANSETTIME = 15; 8969 const FATTR4_CASE_INSENSITIVE = 16; 8970 const FATTR4_CASE_PRESERVING = 17; 8972 Draft Specification NFS version 4 Protocol February 2000 8974 const FATTR4_CHOWN_RESTRICTED = 18; 8975 const FATTR4_FILEHANDLE = 19; 8976 const FATTR4_FILEID = 20; 8977 const FATTR4_FILES_AVAIL = 21; 8978 const FATTR4_FILES_FREE = 22; 8979 const FATTR4_FILES_TOTAL = 23; 8980 const FATTR4_FS_LOCATIONS = 24; 8981 const FATTR4_HIDDEN = 25; 8982 const FATTR4_HOMOGENEOUS = 26; 8983 const FATTR4_MAXFILESIZE = 27; 8984 const FATTR4_MAXLINK = 28; 8985 const FATTR4_MAXNAME = 29; 8986 const FATTR4_MAXREAD = 30; 8987 const FATTR4_MAXWRITE = 31; 8988 const FATTR4_MIMETYPE = 32; 8989 const FATTR4_MODE = 33; 8990 const FATTR4_NO_TRUNC = 34; 8991 const FATTR4_NUMLINKS = 35; 8992 const FATTR4_OWNER = 36; 8993 const FATTR4_OWNER_GROUP = 37; 8994 const FATTR4_QUOTA_HARD = 38; 8995 const FATTR4_QUOTA_SOFT = 39; 8996 const FATTR4_QUOTA_USED = 40; 8997 const FATTR4_RAWDEV = 41; 8998 const FATTR4_SPACE_AVAIL = 42; 8999 const FATTR4_SPACE_FREE = 43; 9000 const FATTR4_SPACE_TOTAL = 44; 9001 const FATTR4_SPACE_USED = 45; 9002 const FATTR4_SYSTEM = 46; 9003 const FATTR4_TIME_ACCESS = 47; 9004 const FATTR4_TIME_ACCESS_SET = 48; 9005 const FATTR4_TIME_BACKUP = 49; 9006 const FATTR4_TIME_CREATE = 50; 9007 const FATTR4_TIME_DELTA = 51; 9008 const FATTR4_TIME_METADATA = 52; 9009 const FATTR4_TIME_MODIFY = 53; 9010 const FATTR4_TIME_MODIFY_SET = 54; 9012 typedef opaque attrlist4<>; 9014 /* 9015 * File attribute container 9016 */ 9017 struct fattr4 { 9018 bitmap4 attrmask; 9019 attrlist4 attr_vals; 9020 }; 9022 Draft Specification NFS version 4 Protocol February 2000 9024 /* 9025 * Change info for the client 9026 */ 9027 struct change_info4 { 9028 bool atomic; 9029 changeid4 before; 9030 changeid4 after; 9031 }; 9033 struct clientaddr4 { 9034 /* see struct rpcb in RFC 1833 */ 9035 string r_netid<>; /* network id */ 9036 string r_addr<>; /* universal address */ 9037 }; 9039 /* 9040 * Callback program info as provided by the client 9041 */ 9042 struct cb_client4 { 9043 unsigned int cb_program; 9044 clientaddr4 cb_location; 9045 }; 9047 /* 9048 * Client ID 9049 */ 9050 struct nfs_client_id4 { 9051 verifier4 verifier; 9052 opaque id<>; 9053 }; 9055 struct nfs_lockowner4 { 9056 clientid4 clientid; 9057 opaque owner<>; 9058 }; 9060 enum nfs_lock_type4 { 9061 READ_LT = 1, 9062 WRITE_LT = 2, 9063 READW_LT = 3, /* blocking read */ 9064 WRITEW_LT = 4 /* blocking write */ 9065 }; 9067 /* 9068 * ACCESS: Check access permission 9069 */ 9070 const ACCESS4_READ = 0x00000001; 9071 const ACCESS4_LOOKUP = 0x00000002; 9073 Draft Specification NFS version 4 Protocol February 2000 9075 const ACCESS4_MODIFY = 0x00000004; 9076 const ACCESS4_EXTEND = 0x00000008; 9077 const ACCESS4_DELETE = 0x00000010; 9078 const ACCESS4_EXECUTE = 0x00000020; 9080 struct ACCESS4args { 9081 /* CURRENT_FH: object */ 9082 uint32_t access; 9083 }; 9085 struct ACCESS4resok { 9086 uint32_t supported; 9087 uint32_t access; 9088 }; 9090 union ACCESS4res switch (nfsstat4 status) { 9091 case NFS4_OK: 9092 ACCESS4resok resok4; 9093 default: 9094 void; 9095 }; 9097 /* 9098 * CLOSE: Close a file and release share locks 9099 */ 9100 struct CLOSE4args { 9101 /* CURRENT_FH: object */ 9102 seqid4 seqid; 9103 stateid4 stateid; 9104 }; 9106 union CLOSE4res switch (nfsstat4 status) { 9107 case NFS4_OK: 9108 stateid4 stateid; 9109 default: 9110 void; 9111 }; 9113 /* 9114 * COMMIT: Commit cached data on server to stable storage 9115 */ 9116 struct COMMIT4args { 9117 /* CURRENT_FH: file */ 9118 offset4 offset; 9119 count4 count; 9120 }; 9122 struct COMMIT4resok { 9124 Draft Specification NFS version 4 Protocol February 2000 9126 verifier4 writeverf; 9127 }; 9129 union COMMIT4res switch (nfsstat4 status) { 9130 case NFS4_OK: 9131 COMMIT4resok resok4; 9132 default: 9133 void; 9134 }; 9136 /* 9137 * CREATE: Create a file 9138 */ 9139 union createtype4 switch (nfs_ftype4 type) { 9140 case NF4LNK: 9141 linktext4 linkdata; 9142 case NF4BLK: 9143 case NF4CHR: 9144 specdata4 devdata; 9145 case NF4SOCK: 9146 case NF4FIFO: 9147 case NF4DIR: 9148 void; 9149 }; 9151 struct CREATE4args { 9152 /* CURRENT_FH: directory for creation */ 9153 component4 objname; 9154 createtype4 objtype; 9155 }; 9157 struct CREATE4resok { 9158 change_info4 cinfo; 9159 }; 9161 union CREATE4res switch (nfsstat4 status) { 9162 case NFS4_OK: 9163 CREATE4resok resok4; 9164 default: 9165 void; 9166 }; 9168 /* 9169 * DELEGPURGE: Purge Delegations Awaiting Recovery 9170 */ 9171 struct DELEGPURGE4args { 9172 clientid4 clientid; 9174 Draft Specification NFS version 4 Protocol February 2000 9176 }; 9178 struct DELEGPURGE4res { 9179 nfsstat4 status; 9180 }; 9182 /* 9183 * DELEGRETURN: Return a delegation 9184 */ 9185 struct DELEGRETURN4args { 9186 stateid4 stateid; 9187 }; 9189 struct DELEGRETURN4res { 9190 nfsstat4 status; 9191 }; 9193 /* 9194 * GETATTR: Get file attributes 9195 */ 9196 struct GETATTR4args { 9197 /* CURRENT_FH: directory or file */ 9198 bitmap4 attr_request; 9199 }; 9201 struct GETATTR4resok { 9202 fattr4 obj_attributes; 9203 }; 9205 union GETATTR4res switch (nfsstat4 status) { 9206 case NFS4_OK: 9207 GETATTR4resok resok4; 9208 default: 9209 void; 9210 }; 9212 /* 9213 * GETFH: Get current filehandle 9214 */ 9215 struct GETFH4resok { 9216 nfs_fh4 object; 9217 }; 9219 union GETFH4res switch (nfsstat4 status) { 9220 case NFS4_OK: 9221 GETFH4resok resok4; 9222 default: 9223 void; 9225 Draft Specification NFS version 4 Protocol February 2000 9227 }; 9229 /* 9230 * LINK: Create link to an object 9231 */ 9232 struct LINK4args { 9233 /* SAVED_FH: source object */ 9234 /* CURRENT_FH: target directory */ 9235 component4 newname; 9236 }; 9238 struct LINK4resok { 9239 change_info4 cinfo; 9240 }; 9242 union LINK4res switch (nfsstat4 status) { 9243 case NFS4_OK: 9244 LINK4resok resok4; 9245 default: 9246 void; 9247 }; 9249 /* 9250 * LOCK/LOCKT/LOCKU: Record lock management 9251 */ 9252 struct LOCK4args { 9253 /* CURRENT_FH: file */ 9254 nfs_lock_type4 locktype; 9255 seqid4 seqid; 9256 bool reclaim; 9257 stateid4 stateid; 9258 offset4 offset; 9259 length4 length; 9260 }; 9262 struct LOCK4denied { 9263 nfs_lockowner4 owner; 9264 offset4 offset; 9265 length4 length; 9266 }; 9268 union LOCK4res switch (nfsstat4 status) { 9269 case NFS4_OK: 9270 stateid4 stateid; 9271 case NFS4ERR_DENIED: 9272 LOCK4denied denied; 9273 default: 9274 void; 9276 Draft Specification NFS version 4 Protocol February 2000 9278 }; 9280 struct LOCKT4args { 9281 /* CURRENT_FH: file */ 9282 nfs_lock_type4 locktype; 9283 nfs_lockowner4 owner; 9284 offset4 offset; 9285 length4 length; 9286 }; 9288 union LOCKT4res switch (nfsstat4 status) { 9289 case NFS4ERR_DENIED: 9290 LOCK4denied denied; 9291 case NFS4_OK: 9292 void; 9293 default: 9294 void; 9295 }; 9297 struct LOCKU4args { 9298 /* CURRENT_FH: file */ 9299 nfs_lock_type4 type; 9300 seqid4 seqid; 9301 stateid4 stateid; 9302 offset4 offset; 9303 length4 length; 9304 }; 9306 union LOCKU4res switch (nfsstat4 status) { 9307 case NFS4_OK: 9308 stateid4 stateid; 9309 default: 9310 void; 9311 }; 9313 /* 9314 * LOOKUP: Lookup filename 9315 */ 9316 struct LOOKUP4args { 9317 /* CURRENT_FH: directory */ 9318 pathname4 path; 9319 }; 9321 struct LOOKUP4res { 9322 /* CURRENT_FH: object */ 9323 nfsstat4 status; 9324 }; 9326 Draft Specification NFS version 4 Protocol February 2000 9328 /* 9329 * LOOKUPP: Lookup parent directory 9330 */ 9331 struct LOOKUPP4res { 9332 /* CURRENT_FH: directory */ 9333 nfsstat4 status; 9334 }; 9336 /* 9337 * NVERIFY: Verify attributes different 9338 */ 9339 struct NVERIFY4args { 9340 /* CURRENT_FH: object */ 9341 bitmap4 attr_request; 9342 fattr4 obj_attributes; 9343 }; 9345 struct NVERIFY4res { 9346 nfsstat4 status; 9347 }; 9349 /* 9350 * Various definitions for OPEN 9351 */ 9352 enum createmode4 { 9353 UNCHECKED4 = 0, 9354 GUARDED4 = 1, 9355 EXCLUSIVE4 = 2 9356 }; 9358 union createhow4 switch (createmode4 mode) { 9359 case UNCHECKED4: 9360 case GUARDED4: 9361 fattr4 createattrs; 9362 case EXCLUSIVE4: 9363 verifier4 createverf; 9364 }; 9366 enum opentype4 { 9367 OPEN4_NOCREATE = 0, 9368 OPEN4_CREATE = 1 9369 }; 9371 union openflag4 switch (opentype4 opentype) { 9372 case OPEN4_CREATE: 9373 createhow4 how; 9374 default: 9375 void; 9377 Draft Specification NFS version 4 Protocol February 2000 9379 }; 9381 /* Next definitions used for OPEN delegation */ 9382 enum limit_by4 { 9383 NFS_LIMIT_SIZE = 1, 9384 NFS_LIMIT_BLOCKS = 2 9385 /* others as needed */ 9386 }; 9388 struct nfs_modified_limit4 { 9389 uint32_t num_blocks; 9390 uint32_t bytes_per_block; 9391 }; 9393 union nfs_space_limit4 switch (limit_by4 limitby) { 9394 /* limit specified as file size */ 9395 case NFS_LIMIT_SIZE: 9396 uint64_t filesize; 9397 /* limit specified by number of blocks */ 9398 case NFS_LIMIT_BLOCKS: 9399 nfs_modified_limit4 mod_blocks; 9400 } ; 9402 /* 9403 * Share Access and Deny constants for open argument 9404 */ 9405 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 9406 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 9407 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 9409 const OPEN4_SHARE_DENY_NONE = 0x00000000; 9410 const OPEN4_SHARE_DENY_READ = 0x00000001; 9411 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 9412 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 9414 enum open_delegation_type4 { 9415 OPEN_DELEGATE_NONE = 0, 9416 OPEN_DELEGATE_READ = 1, 9417 OPEN_DELEGATE_WRITE = 2 9418 }; 9420 enum open_claim_type4 { 9421 CLAIM_NULL = 0, 9422 CLAIM_PREVIOUS = 1, 9423 CLAIM_DELEGATE_CUR = 2, 9424 CLAIM_DELEGATE_PREV = 3 9425 }; 9427 Draft Specification NFS version 4 Protocol February 2000 9429 struct open_claim_delegate_cur4 { 9430 pathname4 file; 9431 stateid4 delegate_stateid; 9432 }; 9434 union open_claim4 switch (open_claim_type4 claim) { 9435 /* 9436 * No special rights to file. Ordinary OPEN of the specified file. 9437 */ 9438 case CLAIM_NULL: 9439 /* CURRENT_FH: directory */ 9440 pathname4 file; 9442 /* 9443 * Right to the file established by an open previous to server 9444 * reboot. File identified by filehandle obtained at that time 9445 * rather than by name. 9446 */ 9447 case CLAIM_PREVIOUS: 9448 /* CURRENT_FH: file being reclaimed */ 9449 uint32_t delegate_type; 9451 /* 9452 * Right to file based on a delegation granted by the server. 9453 * File is specified by name. 9454 */ 9455 case CLAIM_DELEGATE_CUR: 9456 /* CURRENT_FH: directory */ 9457 open_claim_delegate_cur4 delegate_cur_info; 9459 /* Right to file based on a delegation granted to a previous boot 9460 * instance of the client. File is specified by name. 9461 */ 9462 case CLAIM_DELEGATE_PREV: 9463 /* CURRENT_FH: directory */ 9464 pathname4 file_delegate_prev; 9465 }; 9467 /* 9468 * OPEN: Open a file, potentially receiving an open delegation 9469 */ 9470 struct OPEN4args { 9471 open_claim4 claim; 9472 openflag4 openhow; 9473 nfs_lockowner4 owner; 9474 seqid4 seqid; 9475 uint32_t share_access; 9476 uint32_t share_deny; 9478 Draft Specification NFS version 4 Protocol February 2000 9480 }; 9482 struct open_read_delegation4 { 9483 stateid4 stateid; /* Stateid for delegation*/ 9484 bool recall; /* Pre-recalled flag for 9485 delegations obtained 9486 by reclaim 9487 (CLAIM_PREVIOUS) */ 9488 nfsace4 permissions; /* Defines users who don't 9489 need an ACCESS call to 9490 open for read */ 9491 }; 9493 struct open_write_delegation4 { 9494 stateid4 stateid; /* Stateid for delegation 9495 be flushed to the server 9496 on close. */ 9497 bool recall; /* Pre-recalled flag for 9498 delegations obtained 9499 by reclaim 9500 (CLAIM_PREVIOUS) */ 9501 nfs_space_limit4 space_limit; /* Defines condition that 9502 the client must check to 9503 determine whether the 9504 file needs to be flushed 9505 to the server on close. 9506 */ 9507 nfsace4 permissions; /* Defines users who don't 9508 need an ACCESS call as 9509 part of a delegated 9510 open. */ 9511 }; 9513 union open_delegation4 9514 switch (open_delegation_type4 delegation_type) { 9515 case OPEN_DELEGATE_NONE: 9516 void; 9517 case OPEN_DELEGATE_READ: 9518 open_read_delegation4 read; 9519 case OPEN_DELEGATE_WRITE: 9520 open_write_delegation4 write; 9521 }; 9523 /* 9524 * Result flags 9525 */ 9526 /* Mandatory locking is in effect for this file. */ 9527 const OPEN4_RESULT_MLOCK = 0x00000001; 9529 Draft Specification NFS version 4 Protocol February 2000 9531 /* Client must confirm open */ 9532 const OPEN4_RESULT_CONFIRM = 0x00000002; 9534 struct OPEN4resok { 9535 stateid4 stateid; /* Stateid for open */ 9536 change_info4 cinfo; /* Directory Change Info */ 9537 uint32_t rflags; /* Result flags */ 9538 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 9539 open_delegation4 delegation; /* Info on any open 9540 delegation */ 9541 }; 9543 union OPEN4res switch (nfsstat4 status) { 9544 case NFS4_OK: 9545 /* CURRENT_FH: opened file */ 9546 OPEN4resok result; 9547 default: 9548 void; 9549 }; 9551 /* 9552 * OPENATTR: open named attributes directory 9553 */ 9554 struct OPENATTR4res { 9555 /* CURRENT_FH: name attr directory*/ 9556 nfsstat4 status; 9557 }; 9559 /* 9560 * OPEN_CONFIRM: confirm the open 9561 */ 9562 struct OPEN_CONFIRM4args { 9563 /* CURRENT_FH: opened file */ 9564 seqid4 seqid; 9565 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 9566 }; 9568 struct OPEN_CONFIRM4resok { 9569 stateid4 stateid; 9570 }; 9572 union OPEN_CONFIRM4res switch (nfsstat4 status) { 9573 case NFS4_OK: 9574 OPEN_CONFIRM4resok resok4; 9575 default: 9576 void; 9577 }; 9579 Draft Specification NFS version 4 Protocol February 2000 9581 /* 9582 * OPEN_DOWNGRADE: downgrade the access/deny for a file 9583 */ 9584 struct OPEN_DOWNGRADE4args { 9585 /* CURRENT_FH: opened file */ 9586 stateid4 stateid; 9587 seqid4 seqid; 9588 uint32_t share_access; 9589 uint32_t share_deny; 9590 }; 9592 struct OPEN_DOWNGRADE4resok { 9593 stateid4 stateid; 9594 }; 9596 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 9597 case NFS4_OK: 9598 OPEN_DOWNGRADE4resok resok4; 9599 default: 9600 void; 9601 }; 9603 /* 9604 * PUTFH: Set current filehandle 9605 */ 9606 struct PUTFH4args { 9607 nfs_fh4 object; 9608 }; 9610 struct PUTFH4res { 9611 /* CURRENT_FH: */ 9612 nfsstat4 status; 9613 }; 9615 /* 9616 * PUTPUBFH: Set public filehandle 9617 */ 9618 struct PUTPUBFH4res { 9619 /* CURRENT_FH: public fh */ 9620 nfsstat4 status; 9621 }; 9623 /* 9624 * PUTROOTFH: Set root filehandle 9625 */ 9626 struct PUTROOTFH4res { 9627 /* CURRENT_FH: root fh */ 9628 nfsstat4 status; 9630 Draft Specification NFS version 4 Protocol February 2000 9632 }; 9634 /* 9635 * READ: Read from file 9636 */ 9637 struct READ4args { 9638 /* CURRENT_FH: file */ 9639 stateid4 stateid; 9640 offset4 offset; 9641 count4 count; 9642 }; 9644 struct READ4resok { 9645 bool eof; 9646 opaque data<>; 9647 }; 9649 union READ4res switch (nfsstat4 status) { 9650 case NFS4_OK: 9651 READ4resok resok4; 9652 default: 9653 void; 9654 }; 9656 /* 9657 * READDIR: Read directory 9658 */ 9659 struct READDIR4args { 9660 /* CURRENT_FH: directory */ 9661 nfs_cookie4 cookie; 9662 verifier4 cookieverf; 9663 count4 dircount; 9664 count4 maxcount; 9665 bitmap4 attr_request; 9666 }; 9668 struct entry4 { 9669 nfs_cookie4 cookie; 9670 component4 name; 9671 fattr4 attrs; 9672 entry4 *nextentry; 9673 }; 9675 struct dirlist4 { 9676 entry4 *entries; 9677 bool eof; 9678 }; 9680 Draft Specification NFS version 4 Protocol February 2000 9682 struct READDIR4resok { 9683 verifier4 cookieverf; 9684 dirlist4 reply; 9685 }; 9687 union READDIR4res switch (nfsstat4 status) { 9688 case NFS4_OK: 9689 READDIR4resok resok4; 9690 default: 9691 void; 9692 }; 9694 /* 9695 * READLINK: Read symbolic link 9696 */ 9697 struct READLINK4resok { 9698 linktext4 link; 9699 }; 9701 union READLINK4res switch (nfsstat4 status) { 9702 case NFS4_OK: 9703 READLINK4resok resok4; 9704 default: 9705 void; 9706 }; 9708 /* 9709 * REMOVE: Remove filesystem object 9710 */ 9711 struct REMOVE4args { 9712 /* CURRENT_FH: directory */ 9713 component4 target; 9714 }; 9716 struct REMOVE4resok { 9717 change_info4 cinfo; 9718 }; 9720 union REMOVE4res switch (nfsstat4 status) { 9721 case NFS4_OK: 9722 REMOVE4resok resok4; 9723 default: 9724 void; 9725 }; 9727 /* 9729 Draft Specification NFS version 4 Protocol February 2000 9731 * RENAME: Rename directory entry 9732 */ 9733 struct RENAME4args { 9734 /* SAVED_FH: source directory */ 9735 component4 oldname; 9736 /* CURRENT_FH: target directory */ 9737 component4 newname; 9738 }; 9740 struct RENAME4resok { 9741 change_info4 source_cinfo; 9742 change_info4 target_cinfo; 9743 }; 9745 union RENAME4res switch (nfsstat4 status) { 9746 case NFS4_OK: 9747 RENAME4resok resok4; 9748 default: 9749 void; 9750 }; 9752 /* 9753 * RENEW: Renew a Lease 9754 */ 9755 struct RENEW4args { 9756 stateid4 stateid; 9757 }; 9759 struct RENEW4res { 9760 nfsstat4 status; 9761 }; 9763 /* 9764 * RESTOREFH: Restore saved filehandle 9765 */ 9767 struct RESTOREFH4res { 9768 /* CURRENT_FH: value of saved fh */ 9769 nfsstat4 status; 9770 }; 9772 /* 9773 * SAVEFH: Save current filehandle 9774 */ 9775 struct SAVEFH4res { 9776 /* SAVED_FH: value of current fh */ 9777 nfsstat4 status; 9778 }; 9780 Draft Specification NFS version 4 Protocol February 2000 9782 /* 9783 * SECINFO: Obtain Available Security Mechanisms 9784 */ 9785 struct SECINFO4args { 9786 /* CURRENT_FH: */ 9787 component4 name; 9788 }; 9790 /* 9791 * From RFC 2203 9792 */ 9793 enum rpc_gss_svc_t { 9794 RPC_GSS_SVC_NONE = 1, 9795 RPC_GSS_SVC_INTEGRITY = 2, 9796 RPC_GSS_SVC_PRIVACY = 3 9797 }; 9799 struct rpcsec_gss_info { 9800 sec_oid4 oid; 9801 qop4 qop; 9802 rpc_gss_svc_t service; 9803 }; 9805 struct secinfo4 { 9806 uint32_t flavor; 9807 /* null for AUTH_SYS, AUTH_NONE; 9808 contains rpcsec_gss_info for 9809 RPCSEC_GSS. */ 9810 opaque flavor_info<>; 9811 }; 9813 typedef secinfo4 SECINFO4resok<>; 9815 union SECINFO4res switch (nfsstat4 status) { 9816 case NFS4_OK: 9817 SECINFO4resok resok4; 9818 default: 9819 void; 9820 }; 9822 /* 9823 * SETATTR: Set attributes 9824 */ 9825 struct SETATTR4args { 9826 /* CURRENT_FH: target object */ 9827 stateid4 stateid; 9828 fattr4 obj_attributes; 9829 }; 9831 Draft Specification NFS version 4 Protocol February 2000 9833 struct SETATTR4res { 9834 nfsstat4 status; 9835 bitmap4 attrsset; 9836 }; 9838 /* 9839 * SETCLIENTID 9840 */ 9841 struct SETCLIENTID4args { 9842 nfs_client_id4 client; 9843 cb_client4 callback; 9844 }; 9846 struct SETCLIENTID4resok { 9847 clientid4 clientid; 9848 verifier4 setclientid_confirm; 9849 }; 9851 union SETCLIENTID4res switch (nfsstat4 status) { 9852 case NFS4_OK: 9853 SETCLIENTID4resok resok4; 9854 case NFS4ERR_CLID_INUSE: 9855 clientaddr4 client_using; 9856 default: 9857 void; 9858 }; 9860 struct SETCLIENTID_CONFIRM4args { 9861 verifier4 setclientid_confirm; 9862 }; 9864 struct SETCLIENTID_CONFIRM4res { 9865 nfsstat4 status; 9866 }; 9868 /* 9869 * VERIFY: Verify attributes same 9870 */ 9871 struct VERIFY4args { 9872 /* CURRENT_FH: object */ 9873 bitmap4 attr_request; 9874 fattr4 obj_attributes; 9875 }; 9877 struct VERIFY4res { 9878 nfsstat4 status; 9879 }; 9881 Draft Specification NFS version 4 Protocol February 2000 9883 /* 9884 * WRITE: Write to file 9885 */ 9886 enum stable_how4 { 9887 UNSTABLE4 = 0, 9888 DATA_SYNC4 = 1, 9889 FILE_SYNC4 = 2 9890 }; 9892 struct WRITE4args { 9893 /* CURRENT_FH: file */ 9894 stateid4 stateid; 9895 offset4 offset; 9896 stable_how4 stable; 9897 opaque data<>; 9898 }; 9900 struct WRITE4resok { 9901 count4 count; 9902 stable_how4 committed; 9903 verifier4 writeverf; 9904 }; 9906 union WRITE4res switch (nfsstat4 status) { 9907 case NFS4_OK: 9908 WRITE4resok resok4; 9909 default: 9910 void; 9911 }; 9913 /* 9914 * Operation arrays 9915 */ 9917 enum nfs_opnum4 { 9918 OP_ACCESS = 3, 9919 OP_CLOSE = 4, 9920 OP_COMMIT = 5, 9921 OP_CREATE = 6, 9922 OP_DELEGPURGE = 7, 9923 OP_DELEGRETURN = 8, 9924 OP_GETATTR = 9, 9925 OP_GETFH = 10, 9926 OP_LINK = 11, 9927 OP_LOCK = 12, 9928 OP_LOCKT = 13, 9929 OP_LOCKU = 14, 9930 OP_LOOKUP = 15, 9932 Draft Specification NFS version 4 Protocol February 2000 9934 OP_LOOKUPP = 16, 9935 OP_NVERIFY = 17, 9936 OP_OPEN = 18, 9937 OP_OPENATTR = 19, 9938 OP_OPEN_CONFIRM = 20, 9939 OP_OPEN_DOWNGRADE = 21, 9940 OP_PUTFH = 22, 9941 OP_PUTPUBFH = 23, 9942 OP_PUTROOTFH = 24, 9943 OP_READ = 25, 9944 OP_READDIR = 26, 9945 OP_READLINK = 27, 9946 OP_REMOVE = 28, 9947 OP_RENAME = 29, 9948 OP_RENEW = 30, 9949 OP_RESTOREFH = 31, 9950 OP_SAVEFH = 32, 9951 OP_SECINFO = 33, 9952 OP_SETATTR = 34, 9953 OP_SETCLIENTID = 35, 9954 OP_SETCLIENTID_CONFIRM = 36, 9955 OP_VERIFY = 37, 9956 OP_WRITE = 38 9957 }; 9959 union nfs_argop4 switch (nfs_opnum4 argop) { 9960 case OP_ACCESS: ACCESS4args opaccess; 9961 case OP_CLOSE: CLOSE4args opclose; 9962 case OP_COMMIT: COMMIT4args opcommit; 9963 case OP_CREATE: CREATE4args opcreate; 9964 case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; 9965 case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; 9966 case OP_GETATTR: GETATTR4args opgetattr; 9967 case OP_GETFH: void; 9968 case OP_LINK: LINK4args oplink; 9969 case OP_LOCK: LOCK4args oplock; 9970 case OP_LOCKT: LOCK4args oplockt; 9971 case OP_LOCKU: LOCK4args oplocku; 9972 case OP_LOOKUP: LOOKUP4args oplookup; 9973 case OP_LOOKUPP: void; 9974 case OP_NVERIFY: NVERIFY4args opnverify; 9975 case OP_OPEN: OPEN4args opopen; 9976 case OP_OPENATTR: void; 9977 case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; 9978 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4args opopen_downgrade; 9979 case OP_PUTFH: PUTFH4args opputfh; 9980 case OP_PUTPUBFH: void; 9981 case OP_PUTROOTFH: void; 9983 Draft Specification NFS version 4 Protocol February 2000 9985 case OP_READ: READ4args opread; 9986 case OP_READDIR: READDIR4args opreaddir; 9987 case OP_READLINK: void; 9988 case OP_REMOVE: REMOVE4args opremove; 9989 case OP_RENAME: RENAME4args oprename; 9990 case OP_RENEW: RENEW4args oprenew; 9991 case OP_RESTOREFH: void; 9992 case OP_SAVEFH: void; 9993 case OP_SECINFO: SECINFO4args opsecinfo; 9994 case OP_SETATTR: SETATTR4args opsetattr; 9995 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 9996 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args 9997 opsetclientid_confirm; 9998 case OP_VERIFY: VERIFY4args opverify; 9999 case OP_WRITE: WRITE4args opwrite; 10000 }; 10002 union nfs_resop4 switch (nfs_opnum4 resop){ 10003 case OP_ACCESS: ACCESS4res opaccess; 10004 case OP_CLOSE: CLOSE4res opclose; 10005 case OP_COMMIT: COMMIT4res opcommit; 10006 case OP_CREATE: CREATE4res opcreate; 10007 case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; 10008 case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; 10009 case OP_GETATTR: GETATTR4res opgetattr; 10010 case OP_GETFH: GETFH4res opgetfh; 10011 case OP_LINK: LINK4res oplink; 10012 case OP_LOCK: LOCK4res oplock; 10013 case OP_LOCKT: LOCKT4res oplockt; 10014 case OP_LOCKU: LOCKU4res oplocku; 10015 case OP_LOOKUP: LOOKUP4res oplookup; 10016 case OP_LOOKUPP: LOOKUPP4res oplookupp; 10017 case OP_NVERIFY: NVERIFY4res opnverify; 10018 case OP_OPEN: OPEN4res opopen; 10019 case OP_OPENATTR: OPENATTR4res opopenattr; 10020 case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; 10021 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4res opopen_downgrade; 10022 case OP_PUTFH: PUTFH4res opputfh; 10023 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 10024 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 10025 case OP_READ: READ4res opread; 10026 case OP_READDIR: READDIR4res opreaddir; 10027 case OP_READLINK: READLINK4res opreadlink; 10028 case OP_REMOVE: REMOVE4res opremove; 10029 case OP_RENAME: RENAME4res oprename; 10030 case OP_RENEW: RENEW4res oprenew; 10031 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 10032 case OP_SAVEFH: SAVEFH4res opsavefh; 10034 Draft Specification NFS version 4 Protocol February 2000 10036 case OP_SECINFO: SECINFO4res opsecinfo; 10037 case OP_SETATTR: SETATTR4res opsetattr; 10038 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 10039 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4res 10040 opsetclientid_confirm; 10041 case OP_VERIFY: VERIFY4res opverify; 10042 case OP_WRITE: WRITE4res opwrite; 10043 }; 10045 struct COMPOUND4args { 10046 utf8string tag; 10047 uint32_t minorversion; 10048 nfs_argop4 argarray<>; 10049 }; 10051 struct COMPOUND4res { 10052 nfsstat4 status; 10053 utf8string tag; 10054 nfs_resop4 resarray<>; 10055 }; 10057 /* 10058 * Remote file service routines 10059 */ 10060 program NFS4_PROGRAM { 10061 version NFS_V4 { 10062 void 10063 NFSPROC4_NULL(void) = 0; 10065 COMPOUND4res 10066 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 10068 } = 4; 10069 } = 100003; 10071 /* 10072 * NFS4 Callback Procedure Definitions and Program 10073 */ 10075 /* 10076 * CB_GETATTR: Get Current Attributes 10077 */ 10078 struct CB_GETATTR4args { 10079 nfs_fh4 fh; 10080 bitmap4 attr_request; 10081 }; 10083 Draft Specification NFS version 4 Protocol February 2000 10085 struct CB_GETATTR4resok { 10086 fattr4 obj_attributes; 10087 }; 10089 union CB_GETATTR4res switch (nfsstat4 status) { 10090 case NFS4_OK: 10091 CB_GETATTR4resok resok4; 10092 default: 10093 void; 10094 }; 10096 /* 10097 * CB_RECALL: Recall an Open Delegation 10098 */ 10099 struct CB_RECALL4args { 10100 stateid4 stateid; 10101 bool truncate; 10102 nfs_fh4 fh; 10103 }; 10105 struct CB_RECALL4res { 10106 nfsstat4 status; 10107 }; 10109 /* 10110 * Various definitions for CB_COMPOUND 10111 */ 10112 enum nfs_cb_opnum4 { 10113 OP_CB_GETATTR = 3, 10114 OP_CB_RECALL = 4 10115 }; 10117 union nfs_cb_argop4 switch (unsigned argop) { 10118 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 10119 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 10120 }; 10122 union nfs_cb_resop4 switch (unsigned resop){ 10123 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 10124 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 10125 }; 10127 struct CB_COMPOUND4args { 10128 utf8string tag; 10129 uint32_t minorversion; 10130 nfs_cb_argop4 argarray<>; 10131 }; 10133 Draft Specification NFS version 4 Protocol February 2000 10135 struct CB_COMPOUND4res { 10136 nfsstat4 status; 10137 utf8string tag; 10138 nfs_cb_resop4 resarray<>; 10139 }; 10141 /* 10142 * Program number is in the transient range since the client 10143 * will assign the exact transient program number and provide 10144 * that to the server via the SETCLIENTID operation. 10145 */ 10146 program NFS4_CALLBACK { 10147 version NFS_CB { 10148 void 10149 CB_NULL(void) = 0; 10150 CB_COMPOUND4res 10151 CB_COMPOUND(CB_COMPOUND4args) = 1; 10152 } = 1; 10153 } = 40000000; 10155 Draft Specification NFS version 4 Protocol February 2000 10157 19. Bibliography 10159 [Gray] 10160 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 10161 for Distributed File Cache Consistency," Proceedings of the Twelfth 10162 Symposium on Operating Systems Principles, p. 202-210, December 1989. 10164 [ISO10646] 10165 "ISO/IEC 10646-1:1993. International Standard -- Information 10166 technology -- Universal Multiple-Octet Coded Character Set (UCS) -- 10167 Part 1: Architecture and Basic Multilingual Plane." 10169 [Juszczak] 10170 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 10171 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 10172 CA, June 1990, pages 53-63. Describes reply cache implementation 10173 that avoids work in the server by handling duplicate requests. More 10174 important, though listed as a side-effect, the reply cache aids in 10175 the avoidance of destructive non-idempotent operation re-application 10176 -- improving correctness. 10178 [Kazar] 10179 Kazar, Michael Leon, "Synchronization and Caching Issues in the 10180 Andrew File System," USENIX Conference Proceedings, USENIX 10181 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 10182 description of the cache consistency scheme in AFS. Contrasted with 10183 other distributed file systems. 10185 [Macklem] 10186 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 10187 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 10188 Association, Berkeley, CA, January 1991. Describes performance work 10189 in tuning the 4.3BSD Reno NFS implementation. Describes performance 10190 improvement (reduced CPU loading) through elimination of data copies. 10192 [Mogul] 10193 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 10194 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 10195 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 10196 lease-based scheme for recovering state of consistency protocol. 10198 Draft Specification NFS version 4 Protocol February 2000 10200 [Nowicki] 10201 Nowicki, Bill, "Transport Issues in the Network File System," ACM 10202 SIGCOMM newsletter Computer Communication Review, April 1989. A 10203 brief description of the basis for the dynamic retransmission work. 10205 [Pawlowski] 10206 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 10207 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 10208 Conf. Proc., (1989) Description of an NFS server implementation for 10209 IBM's MVS operating system. 10211 [RFC1094] 10212 Sun Microsystems, Inc., "NFS: Network File System Protocol 10213 Specification", RFC1094, March 1989. 10215 http://www.ietf.org/rfc/rfc1094.txt 10217 [RFC1345] 10218 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 10219 Rationel Almen Planlaegning, June 1992. 10221 http://www.ietf.org/rfc/rfc1345.txt 10223 [RFC1700] 10224 Reynolds, J., Postel, J., "Assigned Numbers", RFC1700, ISI, October 10225 1994 10227 http://www.ietf.org/rfc/rfc1700.txt 10229 [RFC1813] 10230 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 10231 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 10233 http://www.ietf.org/rfc/rfc1813.txt 10235 [RFC1831] 10236 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 10237 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 10239 http://www.ietf.org/rfc/rfc1831.txt 10241 Draft Specification NFS version 4 Protocol February 2000 10243 [RFC1832] 10244 Srinivasan, R., "XDR: External Data Representation Standard", 10245 RFC1832, Sun Microsystems, Inc., August 1995. 10247 http://www.ietf.org/rfc/rfc1832.txt 10249 [RFC1833] 10250 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 10251 Sun Microsystems, Inc., August 1995. 10253 http://www.ietf.org/rfc/rfc1833.txt 10255 [RFC2025] 10256 Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", RFC2025, 10257 Bell-Northern Research, October 1996. 10259 http://www.ietf.org/rfc/rfc2026.txt 10261 [RFC2054] 10262 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 10263 Microsystems, Inc., October 1996 10265 http://www.ietf.org/rfc/rfc2054.txt 10267 [RFC2055] 10268 Callaghan, B., "WebNFS Server Specification", RFC2055, Sun 10269 Microsystems, Inc., October 1996 10271 http://www.ietf.org/rfc/rfc2055.txt 10273 [RFC2078] 10274 Linn, J., "Generic Security Service Application Program Interface, 10275 Version 2", RFC2078, OpenVision Technologies, January 1997. 10277 http://www.ietf.org/rfc/rfc2078.txt 10279 [RFC2152] 10280 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 10281 RFC2152, Apple Computer, Inc., May 1997 10283 http://www.ietf.org/rfc/rfc2152.txt 10285 Draft Specification NFS version 4 Protocol February 2000 10287 [RFC2203] 10288 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 10289 RFC2203, Sun Microsystems, Inc., August 1995. 10291 http://www.ietf.org/rfc/rfc2203.txt 10293 [RFC2277] 10294 Alvestrand, H., "IETF Policy on Character Sets and Languages", 10295 RFC2277, UNINETT, January 1998. 10297 http://www.ietf.org/rfc/rfc2277.txt 10299 [RFC2279] 10300 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 10301 Alis Technologies, January 1998. 10303 http://www.ietf.org/rfc/rfc2279.txt 10305 [RFC2623] 10306 Eisler, M., "NFS Version 2 and Version 3 Security Issues and the NFS 10307 Protocol's Use of RPCSEC_GSS and Kerberos V5", RFC2623, Sun 10308 Microsystems, June 1999 10310 http://www.ietf.org/rfc/rfc2623.txt 10312 [RFC2624] 10313 Shepler, S., "NFS Version 4 Design Considerations", RFC2624, Sun 10314 Microsystems, June 1999 10316 http://www.ietf.org/rfc/rfc2624.txt 10318 [RFCXXXX] 10319 Eisler, M., "LIPKEY - A Low Infrastructure Public Key Mechanism Using 10320 SPKM", RFCXXXX, Sun Microsystems, December 1999 10322 http://www.ietf.org/internet-drafts/draft-ietf-cat-lipkey-03.txt 10324 [Sandberg] 10325 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 10326 and Implementation of the Sun Network Filesystem," USENIX Conference 10327 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 10328 basic paper describing the SunOS implementation of the NFS version 2 10330 Draft Specification NFS version 4 Protocol February 2000 10332 protocol, and discusses the goals, protocol specification and trade- 10333 offs. 10335 [Srinivasan] 10336 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 10337 Performance of Cache Consistency Protocols", WRL Research Report 10338 89/5, Digital Equipment Corporation Western Research Laboratory, 100 10339 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 10340 the effect of applying a Sprite-like consistency protocol applied to 10341 standard NFS. The issues of recovery in a stateful environment are 10342 covered in [Mogul]. 10344 [Unicode1] 10345 The Unicode Consortium, "The Unicode Standard, Version 3.0", 10346 Addison-Wesley Developers Press, Reading, MA, 2000. ISBN 0-201- 10347 61633-5. 10349 More information available at: http://www.unicode.org/ 10351 [Unicode2] 10352 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 10353 700519, San Jose, CA 95710-0519 USA, September 1999 10355 http://www.unicode.org/unicode/standard/unsupported.html 10357 [XNFS] 10358 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 10359 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 10360 1-85912-184-5, February 1998. 10362 HTML version available: http://www.opengroup.org 10364 Draft Specification NFS version 4 Protocol February 2000 10366 20. Authors 10368 20.1. Editor's Address 10370 Spencer Shepler 10371 Sun Microsystems, Inc. 10372 7808 Moonflower Drive 10373 Austin, Texas 78750 10375 Phone: +1 512-349-9376 10376 E-mail: shepler@eng.sun.com 10378 20.2. Authors' Addresses 10380 Carl Beame 10381 Hummingbird Communications Ltd. 10383 E-mail: beame@bws.com 10385 Brent Callaghan 10386 Sun Microsystems, Inc. 10387 901 San Antonio Road 10388 Palo Alto, CA 94303 10390 Phone: +1 650-786-5067 10391 E-mail: brent.callaghan@eng.sun.com 10393 Mike Eisler 10394 Sun Microsystems, Inc. 10395 5565 Wilson Road 10396 Colorado Springs, CO 80919 10398 Phone: +1 719-599-9026 10399 E-mail: mre@eng.sun.com 10401 Dave Noveck 10402 Network Appliance 10403 495 East Java Drive 10404 Sunnyvale, CA 94089 10406 Phone: +1 781-861-9291 10407 E-mail: dave.noveck@netapp.com 10409 Draft Specification NFS version 4 Protocol February 2000 10411 David Robinson 10412 Sun Microsystems, Inc. 10413 901 San Antonio Road 10414 Palo Alto, CA 94303 10416 Phone: +1 650-786-5088 10417 E-mail: david.robinson@eng.sun.com 10419 Robert Thurlow 10420 Sun Microsystems, Inc. 10421 901 San Antonio Road 10422 Palo Alto, CA 94303 10424 Phone: +1 650-786-5096 10425 E-mail: robert.thurlow@eng.sun.com 10427 Draft Specification NFS version 4 Protocol February 2000 10429 21. Full Copyright Statement 10431 "Copyright (C) The Internet Society (2000). All Rights Reserved. 10433 This document and translations of it may be copied and furnished to 10434 others, and derivative works that comment on or otherwise explain it 10435 or assist in its implementation may be prepared, copied, published 10436 and distributed, in whole or in part, without restriction of any 10437 kind, provided that the above copyright notice and this paragraph are 10438 included on all such copies and derivative works. However, this 10439 document itself may not be modified in any way, such as by removing 10440 the copyright notice or references to the Internet Society or other 10441 Internet organizations, except as needed for the purpose of 10442 developing Internet standards in which case the procedures for 10443 copyrights defined in the Internet Standards process must be 10444 followed, or as required to translate it into languages other than 10445 English. 10447 The limited permissions granted above are perpetual and will not be 10448 revoked by the Internet Society or its successors or assigns. 10450 This document and the information contained herein is provided on an 10451 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 10452 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 10453 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 10454 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 10455 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."