idnits 2.17.1 draft-ietf-nfsv4-04.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 150) being 61 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 247 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 577 has weird spacing: '...ned int uin...' == Line 581 has weird spacing: '...d hyper uint6...' == Line 646 has weird spacing: '...8string typ...' == Line 711 has weird spacing: '...8string ser...' == Line 777 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 (January 2000) is 8867 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 10075 looks like a reference -- Missing reference section? 'RFC1813' on line 10093 looks like a reference -- Missing reference section? 'RFC1831' on line 10099 looks like a reference -- Missing reference section? 'RFC1832' on line 10105 looks like a reference -- Missing reference section? 'RFC2623' on line 10169 looks like a reference -- Missing reference section? 'RFC1964' on line 863 looks like a reference -- Missing reference section? 'RFCXXXX' on line 10182 looks like a reference -- Missing reference section? 'RFC2078' on line 10137 looks like a reference -- Missing reference section? 'RFC2203' on line 10149 looks like a reference -- Missing reference section? 'RFC1700' on line 10087 looks like a reference -- Missing reference section? 'RFC1833' on line 10113 looks like a reference -- Missing reference section? 'RFC2581' on line 829 looks like a reference -- Missing reference section? 'RFC2025' on line 10119 looks like a reference -- Missing reference section? 'RFC2054' on line 10125 looks like a reference -- Missing reference section? 'RFC2055' on line 10131 looks like a reference -- Missing reference section? 'RFC2624' on line 10176 looks like a reference -- Missing reference section? 'XNFS' on line 10221 looks like a reference -- Missing reference section? '4' on line 2439 looks like a reference -- Missing reference section? 'Juszczak' on line 10033 looks like a reference -- Missing reference section? 'RFC2277' on line 10157 looks like a reference -- Missing reference section? 'RFC1345' on line 10081 looks like a reference -- Missing reference section? 'RFC2279' on line 10163 looks like a reference -- Missing reference section? 'RFC2152' on line 10143 looks like a reference -- Missing reference section? 'Unicode1' on line 10208 looks like a reference -- Missing reference section? 'Unicode2' on line 10215 looks like a reference -- Missing reference section? 'Gray' on line 10028 looks like a reference -- Missing reference section? 'Kazar' on line 10042 looks like a reference -- Missing reference section? 'Macklem' on line 10049 looks like a reference -- Missing reference section? 'Mogul' on line 10206 looks like a reference -- Missing reference section? 'Nowicki' on line 10062 looks like a reference -- Missing reference section? 'Pawlowski' on line 10069 looks like a reference -- Missing reference section? 'Sandberg' on line 10188 looks like a reference -- Missing reference section? 'Srinivasan' on line 10196 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 11 warnings (==), 36 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 NFS Version 4 Working Group S. Shepler 2 INTERNET-DRAFT Sun Microsystems 3 Document: draft-ietf-nfsv4-04.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 January 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 January 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 January 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 January 2000 118 5.8.2. ACE flag . . . . . . . . . . . . . . . . . . . . . . . 44 119 5.8.3. ACE Access Mask . . . . . . . . . . . . . . . . . . . 45 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 January 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 12. Error Definitions . . . . . . . . . . . . . . . . . . . . 100 187 13. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 105 188 13.1. Compound Procedure . . . . . . . . . . . . . . . . . . 105 189 13.2. Evaluation of a Compound Request . . . . . . . . . . . 106 190 13.3. Operation Values . . . . . . . . . . . . . . . . . . . 106 191 14. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 107 192 14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 107 193 14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 108 194 14.2.1. Operation 3: ACCESS - Check Access Rights . . . . . . 111 195 14.2.2. Operation 4: CLOSE - Close File . . . . . . . . . . . 115 196 14.2.3. Operation 5: COMMIT - Commit Cached Data . . . . . . 117 197 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 120 198 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 199 Recovery . . . . . . . . . . . . . . . . . . . . . . 123 200 14.2.6. Operation 8: DELEGRETURN - Return Delegation . . . . 124 201 14.2.7. Operation 9: GETATTR - Get Attributes . . . . . . . . 125 202 14.2.8. Operation 10: GETFH - Get Current Filehandle . . . . 127 203 14.2.9. Operation 11: LINK - Create Link to a File . . . . . 129 204 14.2.10. Operation 12: LOCK - Create Lock . . . . . . . . . . 131 205 14.2.11. Operation 13: LOCKT - Test For Lock . . . . . . . . 134 206 14.2.12. Operation 14: LOCKU - Unlock File . . . . . . . . . 136 207 14.2.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . 138 208 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory . . 141 209 14.2.15. Operation 17: NVERIFY - Verify Difference in 210 Attributes . . . . . . . . . . . . . . . . . . . . . 143 211 14.2.16. Operation 18: OPEN - Open a Regular File . . . . . . 145 212 14.2.17. Operation 19: OPENATTR - Open Named Attribute 213 Directory . . . . . . . . . . . . . . . . . . . . . 154 214 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . 156 215 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access159 216 14.2.20. Operation 22: PUTFH - Set Current Filehandle . . . . 161 218 Draft Specification NFS version 4 Protocol January 2000 220 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle . . . 162 221 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle . . . 163 222 14.2.23. Operation 25: READ - Read from File . . . . . . . . 164 223 14.2.24. Operation 26: READDIR - Read Directory . . . . . . . 167 224 14.2.25. Operation 27: READLINK - Read Symbolic Link . . . . 171 225 14.2.26. Operation 28: REMOVE - Remove Filesystem Object . . 173 226 14.2.27. Operation 29: RENAME - Rename Directory Entry . . . 175 227 14.2.28. Operation 30: RENEW - Renew a Lease . . . . . . . . 178 228 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle . 180 229 14.2.30. Operation 32: SAVEFH - Save Current Filehandle . . . 182 230 14.2.31. Operation 33: SECINFO - Obtain Available Security . 183 231 14.2.32. Operation 34: SETATTR - Set Attributes . . . . . . . 185 232 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid . . . 188 233 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 190 234 14.2.35. Operation 37: VERIFY - Verify Same Attributes . . . 192 235 14.2.36. Operation 38: WRITE - Write to File . . . . . . . . 194 236 15. NFS Version 4 Callback Procedures . . . . . . . . . . . . 199 237 15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 199 238 15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 200 239 15.2.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . 202 240 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation . 204 241 16. Security Considerations . . . . . . . . . . . . . . . . . 206 242 17. IANA Considerations . . . . . . . . . . . . . . . . . . . 207 243 17.1. Named Attribute Definition . . . . . . . . . . . . . . 207 244 18. RPC definition file . . . . . . . . . . . . . . . . . . . 208 245 19. Bibliography . . . . . . . . . . . . . . . . . . . . . . 240 246 20. Authors and Contributors . . . . . . . . . . . . . . . . 245 247 20.1. Editor's Address . . . . . . . . . . . . . . . . . . . 245 248 20.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 245 249 21. Full Copyright Statement . . . . . . . . . . . . . . . . 247 251 Draft Specification NFS version 4 Protocol January 2000 253 1. Introduction 255 The NFS version 4 protocol is a further revision of the NFS protocol 256 defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains 257 the essential characteristics of previous versions: design for easy 258 recovery, independent of transport protocols, operating systems and 259 filesystems, simplicity, and good performance. The NFS version 4 260 revision has the following goals: 262 o Improved access and good performance on the Internet. 264 The protocol is designed to transit firewalls easily, perform 265 well where latency is high and bandwidth is low, and scale to 266 very large numbers of clients per server. 268 o Strong security with negotiation built into the protocol. 270 The protocol builds on the work of the ONCRPC working group in 271 supporting the RPCSEC_GSS protocol. Additionally, the NFS 272 version 4 protocol provides a mechanism to allow clients and 273 servers the ability to negotiate security and require clients 274 and servers to support a minimal set of security schemes. 276 o Good cross-platform interoperability. 278 The protocol features a file system model that provides a 279 useful, common set of features that does not unduly favor one 280 file system or operating system over another. 282 o Designed for protocol extensions. 284 The protocol is designed to accept standard extensions that do 285 not compromise backward compatibility. 287 1.1. Overview of NFS Version 4 Features 289 To provide a reasonable context for the reader, the major features of 290 NFS version 4 protocol will be reviewed in brief. This will be done 291 to provide an appropriate context for both the reader who is familiar 292 with the previous versions of the NFS protocol and the reader that is 293 new to the NFS protocols. For the reader new to the NFS protocols, 294 there is still a fundamental knowledge that is expected. The reader 295 should be familiar with the XDR and RPC protocols as described in 297 Draft Specification NFS version 4 Protocol January 2000 299 [RFC1831] and [RFC1832]. A basic knowledge of file systems and 300 distributed file systems is expected as well. 302 1.1.1. RPC and Security 304 As with previous versions of NFS, the External Data Representation 305 (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS 306 version 4 protocol are those defined in [RFC1831] and [RFC1832]. To 307 meet end to end security requirements, the RPCSEC_GSS framework 308 [RFC2623] will be used to extend the basic RPC security. With the 309 use of RPCSEC_GSS, various mechanisms can be provided to offer 310 authentication, integrity, and privacy to the NFS version 4 protocol. 311 Kerberos V5 will be used as described in [RFC1964] to provide one 312 security framework. The LIPKEY GSS-API mechanism described in 313 [RFCXXXX] will be used to provide for the use of user password and 314 server public key by the NFS version 4 protocol. With the use of 315 RPCSEC_GSS, other mechanisms may also be specified and used for NFS 316 version 4 security. 318 To enable in-band security negotiation, the NFS version 4 protocol 319 has added a new operation which provides the client a method of 320 querying the server about its policies regarding which security 321 mechanisms must be used for access to the server's file system 322 resources. With this, the client can securely match the security 323 mechanism that meets the policies specified at both the client and 324 server. 326 1.1.2. Procedure and Operation Structure 328 A significant departure from the previous versions of the NFS 329 protocol is the introduction of the COMPOUND procedure. For the NFS 330 version 4 protocol, there are two RPC procedures, NULL and COMPOUND. 331 The COMPOUND procedure is defined in terms of operations and these 332 operations correspond more closely to the traditional NFS procedures. 333 With the use of the COMPOUND procedure, the client is able to build 334 simple or complex requests. These COMPOUND requests allow for a 335 reduction in the number of RPCs needed for logical file system 336 operations. For example, without previous contact with a server a 337 client will be able to read data from a file in one request by 338 combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. 339 With previous versions of the NFS protocol, this type of single 340 request was not possible. 342 The model used for COMPOUND is very simple. There is no logical OR 343 or ANDing of operations. The operations combined within a COMPOUND 344 request are evaluated in order by the server. Once an operation 346 Draft Specification NFS version 4 Protocol January 2000 348 returns a failing result, the evaluation ends and the results of all 349 evaluated operations are returned to the client. 351 The NFS version 4 protocol continues to have the client refer to a 352 file or directory at the server by a "filehandle". The COMPOUND 353 procedure has a method of passing a filehandle from one operation to 354 another within the sequence of operations. There is a concept of a 355 "current filehandle" and "saved filehandle". Most operations use the 356 "current filehandle" as the file system object to operate upon. The 357 "saved filehandle" is used as temporary filehandle storage within a 358 COMPOUND procedure as well as an additional operand for certain 359 operations. 361 1.1.3. File System Model 363 The general file system model used for the NFS version 4 protocol is 364 the same as previous versions. The server file system is 365 hierarchical with the regular files contained within being treated as 366 opaque byte streams. In a slight departure, file and directory names 367 are encoded with UTF-8 to deal with the basics of 368 internationalization. 370 The NFS version 4 protocol does not require a separate protocol to 371 provide for the initial mapping between path name and filehandle. 372 Instead of using the older MOUNT protocol for this mapping, the 373 server provides a ROOT filehandle that represents the logical root or 374 top of the file system tree provided by the server. The server 375 provides multiple file systems by glueing them together with pseudo 376 file systems. These pseudo file systems provide for potential gaps 377 in the path names between real file systems. 379 1.1.3.1. Filehandle Types 381 In previous versions of the NFS protocol, the filehandle provided by 382 the server was guaranteed to be valid or persistent for the lifetime 383 of the file system object to which it referred. For some server 384 implementations, this persistence requirement has been difficult to 385 meet. For the NFS version 4 protocol, this requirement has been 386 relaxed by introducing another type of filehandle, volatile. With 387 persistent and volatile filehandle types, the server implementation 388 can match the abilities of the file system at the server along with 389 the operating environment. The client will have knowledge of the 390 type of filehandle being provided by the server and can be prepared 391 to deal with the semantics of each. 393 Draft Specification NFS version 4 Protocol January 2000 395 1.1.3.2. Attribute Types 397 The NFS version 4 protocol introduces three classes of file system or 398 file attributes. Like the additional filehandle type, the 399 classification of file attributes has been done to ease server 400 implementations along with extending the overall functionality of the 401 NFS protocol. This attribute model is structured to be extensible 402 such that new attributes can be introduced in minor revisions of the 403 protocol without requiring significant rework. 405 The three classifications are: mandatory, recommended and named 406 attributes. This is a significant departure from the previous 407 attribute model used in the NFS protocol. Previously, the attributes 408 for the file system and file objects were a fixed set of mainly Unix 409 attributes. If the server or client did not support a particular 410 attribute, it would have to simulate the attribute the best it could. 412 Mandatory attributes are the minimal set of file or file system 413 attributes that must be provided by the server and must be properly 414 represented by the server. Recommended attributes represent 415 different file system types and operating environments. The 416 recommended attributes will allow for better interoperability and the 417 inclusion of more operating environments. The mandatory and 418 recommended attribute sets are traditional file or file system 419 attributes. The third type of attribute is the named attribute. A 420 named attribute is an opaque byte stream that is associated with a 421 directory or file and referred to by a string name. Named attributes 422 are meant to be used by client applications as a method to associate 423 application specific data with a regular file or directory. 425 One significant addition to the recommended set of file attributes is 426 the Access Control List (ACL) attribute. This attribute provides for 427 directory and file access control beyond the model used in previous 428 versions of the NFS protocol. The ACL definition allows for 429 specification of user and group level access control. 431 1.1.3.3. File System Replication and Migration 433 With the use of a special file attribute, the ability to migrate or 434 replicate server file systems is enabled within the protocol. The 435 file system locations attribute provides a method for the client to 436 probe the server about the location of a file system. In the event 437 of a migration of a file system, the client will receive an error 438 when operating on the file system and it can then query as to the new 439 file system location. Similar steps are used for replication, the 440 client is able to query the server for the multiple available 441 locations of a particular file system. From this information, the 443 Draft Specification NFS version 4 Protocol January 2000 445 client can use its own policies to access the appropriate file system 446 location. 448 1.1.4. OPEN and CLOSE 450 The NFS version 4 protocol introduces OPEN and CLOSE operations. The 451 OPEN operation provides a single point where file lookup, creation, 452 and share semantics can be combined. The CLOSE operation also 453 provides for the release of state accumulated by OPEN. 455 1.1.5. File locking 457 With the NFS version 4 protocol, the support for byte range file 458 locking is part of the NFS protocol. The file locking support is 459 structured so that an RPC callback mechanism is not required. This 460 is a departure from the previous versions of the NFS file locking 461 protocol, Network Lock Manager (NLM). The state associated with file 462 locks is maintained at the server under a lease-based model. The 463 server defines a single lease period for all state held by a NFS 464 client. If the client does not renew its lease within the defined 465 period, all state associated with the client's lease may be released 466 by the server. The client may renew its lease with use of the RENEW 467 operation or implicitly by use of other operations (primarily READ). 469 1.1.6. Client Caching and Delegation 471 The file, attribute, and directory caching for the NFS version 4 472 protocol is similar to previous versions. Attributes and directory 473 information are cached for a duration determined by the client. At 474 the end of a predefined timeout, the client will query the server to 475 see if the related file system object has been updated. 477 For file data, the client checks its cache validity when the file is 478 opened. A query is sent to the server to determine if the file has 479 been changed. Based on this information, the client determines if 480 the data cache for the file should kept or released. Also, when the 481 file is closed, any modified data is written to the server. 483 If an application wants to serialize access to file data, file 484 locking of the file data ranges in question should be used. 486 The major addition to NFS version 4 in the area of caching is the 487 ability of the server to delegate certain responsibilities to the 488 client. When the server grants a delegation for a file to a client, 489 the client is guaranteed certain semantics with respect to the 491 Draft Specification NFS version 4 Protocol January 2000 493 sharing of that file with other clients. At OPEN, the server may 494 provid the client either a read or write delegation for the file. If 495 the client is granted a read delegation, it is assured that no other 496 client has the ability to write to the file for the duration of the 497 delegation. If the client is granted a write delegation, the client 498 is assured that no other client has read or write access to the file. 500 Delegations can be recalled by the server. If another client 501 requests access to the file in such a way that the access conflicts 502 with the granted delegation, the server is able to notify the initial 503 client and recall the delegation. This requires that a callback path 504 exist between the server and client. If this callback path does not 505 exist, then delegations can not be granted. The essence of a 506 delegation is that it allows the client to locally service operations 507 such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate 508 interaction with the server. 510 1.2. General Definitions 512 The following definitions are provided for the purpose of providing 513 an appropriate context for the reader. 515 Client The "client" is the entity that accesses the NFS server's 516 resources. The client may be an application which contains 517 the logic to access the NFS server directly. The client 518 may also be the traditional operating system client remote 519 file system services for a set of applications. 521 In the case of file locking the client is the entity that 522 maintains a set of locks on behalf of one or more 523 applications. This client is responsible for crash or 524 failure recovery for those locks it manages. 526 Note that multiple clients may share the same transport and 527 multiple clients may exist on the same network node. 529 Clientid A 64-bit quantity used as a unique, short-hand reference to 530 a client supplied Verifier and ID. The server is 531 responsible for supplying the Clientid. 533 Lease An interval of time defined by the server for which the 534 client is irrevokeably granted a lock. At the end of a 535 lease period the lock may be revoked if the lease has not 536 been extended. The lock must be revoked if a conflicting 537 lock has been granted after the lease interval. 539 Draft Specification NFS version 4 Protocol January 2000 541 All leases granted by a server have the same fixed 542 interval. 544 Lock The term "lock" is used to refer to both record (byte- 545 range) locks as well as file (share) locks unless 546 specifically stated otherwise. 548 Server The "Server" is the entity responsible for coordinating 549 client access to a set of file systems. 551 Stateid A 64-bit quantity returned by a server that uniquely 552 defines the locking state granted by the server for a 553 specific lock owner for a specific file. 555 A stateid composed of all bits 0 or all bits 1 has special 556 meaning and are reserved values. 558 Verifier A 64-bit quantity generated by the client that the server 559 can use to determine if the client has restarted and lost 560 all previous lock state. 562 Draft Specification NFS version 4 Protocol January 2000 564 2. Protocol Data Types 566 The syntax and semantics to describe the data types of the NFS 567 version 4 protocol are defined in the XDR [RFC1832] and RPC [RFC1831] 568 documents. The next sections build upon the XDR data types to define 569 types and structures specific to this protocol. 571 2.1. Basic Data Types 573 Data Type Definition 574 _____________________________________________________________________ 575 int32_t typedef int int32_t; 577 uint32_t typedef unsigned int uint32_t; 579 int64_t typedef hyper int64_t; 581 uint64_t typedef unsigned hyper uint64_t; 583 attrlist4 typedef opaque attrlist4<>; 584 Used for file/directory attributes 586 bitmap4 typedef uint32_t bitmap4<>; 587 Used in attribute array encoding. 589 changeid4 typedef uint64_t changeid4; 590 Used in definition of change_info 592 clientid4 typedef uint64_t clientid4; 593 Shorthand reference to client identification 595 component4 typedef utf8string component4; 596 Represents path name components 598 count4 typedef uint32_t count4; 599 Various count parameters (READ, WRITE, COMMIT) 601 length4 typedef uint64_t length4; 602 Describes LOCK lengths 604 linktext4 typedef utf8string linktext4; 605 Symbolic link contents 607 mode4 typedef uint32_t mode4; 608 Mode attribute data type 610 nfs_cookie4 typedef uint64_t nfs_cookie4; 611 Opaque cookie value for READDIR 613 Draft Specification NFS version 4 Protocol January 2000 615 nfs_fh4 typedef opaque nfs_fh4; 616 Filehandle definition; NFS4_FHSIZE is defined as 128 618 nfs_ftype4 enum nfs_ftype4; 619 Various defined file types 621 nfsstat4 enum nfsstat4; 622 Return value for operations 624 offset4 typedef uint64_t offset4; 625 Various offset designations (READ, WRITE, LOCK, COMMIT) 627 pathname4 typedef component4 pathname4<>; 628 Represents path name for LOOKUP, OPEN and others 630 qop4 typedef uint32_t qop4; 631 Quality of protection designation in SECINFO 633 sec_oid4 typedef opaque sec_oid4<>; 634 Security Object Identifier 635 The sec_oid4 data type is not really opaque. 636 Instead contains an ASN.1 OBJECT IDENTIFIER as used 637 by GSS-API in the mech_type argument to 638 GSS_Init_sec_context. See [RFC2078] for details. 640 seqid4 typedef uint32_t seqid4; 641 Sequence identifier used for file locking 643 stateid4 typedef uint64_t stateid4; 644 State identifier used for file locking and delegation 646 utf8string typedef opaque utf8string<>; 647 UTF-8 encoding for strings 649 verifier4 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 650 Verifier used for various operations (COMMIT, CREATE, 651 OPEN, READDIR, SETCLIENTID, WRITE) 652 NFS4_VERIFIER_SIZE is defined as 8 654 2.2. Structured Data Types 656 nfstime4 657 struct nfstime4 { 658 int64_t seconds; 659 uint32_t nseconds; 661 Draft Specification NFS version 4 Protocol January 2000 663 } 665 The nfstime4 structure gives the number of seconds and 666 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 667 Universal Time (UTC). Values greater than zero for the seconds 668 field denote dates after the 0 hour January 1, 1970. Values 669 less than zero for the seconds field denote dates before the 0 670 hour January 1, 1970. In both cases, the nseconds field is to 671 be added to the seconds field for the final time representation. 672 For example, if the time to be represented is one-half second 673 before 0 hour January 1, 1970, the seconds field would have a 674 value of negative one (-1) and the nseconds fields would have a 675 value of one-half second (500000000). Values greater than 676 999,999,999 for nseconds are considered invalid. 678 This data type is used to pass time and date information. A 679 server converts to and from local time when processing time 680 values, preserving as much accuracy as possible. If the 681 precision of timestamps stored for a file system object is less 682 than defined, loss of precision can occur. An adjunct time 683 maintenance protocol is recommended to reduce client and server 684 time skew. 686 specdata4 688 struct specdata4 { 689 uint32_t specdata1; 690 uint32_t specdata2; 691 } 693 This data type represents additional information for the device 694 file types NF4CHR and NF4BLK. 696 fsid4 698 struct fsid4 { 699 uint64_t major; 700 uint64_t minor; 701 }; 703 This type is the file system identifier that is used as a 704 mandatory attribute. 706 fs_location4 708 Draft Specification NFS version 4 Protocol January 2000 710 struct fs_location4 { 711 utf8string server<>; 712 pathname4 rootpath; 713 }; 715 fs_locations4 717 struct fs_locations4 { 718 pathname4 fs_root; 719 fs_location4 locations<>; 720 }; 722 The fs_location4 and fs_locations4 data types are used for the 723 fs_locations recommended attribute which is used for migration 724 and replication support. 726 fattr4 728 struct fattr4 { 729 bitmap4 attrmask; 730 attrlist4 attr_vals; 731 }; 733 The fattr4 structure is used to represent file and directory 734 attributes. 736 The bitmap is a counted array of 32 bit integers used to contain 737 bit values. The position of the integer in the array that 738 contains bit n can be computed from the expression (n / 32) and 739 its bit within that integer is (n mod 32). 741 0 1 742 +-----------+-----------+-----------+-- 743 | count | 31 .. 0 | 63 .. 32 | 744 +-----------+-----------+-----------+-- 746 change_info4 748 struct change_info4 { 749 bool atomic; 750 changeid4 before; 751 changeid4 after; 752 }; 754 This structure is used with the CREATE, LINK, REMOVE, RENAME 756 Draft Specification NFS version 4 Protocol January 2000 758 operations to let the client know value of the change attribute 759 for the directory in which the target file system object 760 resides. 762 clientaddr4 764 struct clientaddr4 { 765 /* see struct rpcb in RFC 1833 */ 766 string r_netid<>; /* network id */ 767 string r_addr<>; /* universal address */ 768 }; 770 The clientaddr4 structure is used as part of the SETCLIENT 771 operation to specify the address of either the client that is 772 using a clientid or as part of the call back registration. 774 cb_client4 776 struct cb_client4 { 777 unsigned int cb_program; 778 clientaddr4 cb_location; 779 }; 781 This structure is used by the client to inform the server of its 782 call back address; includes the program number and client 783 address. 785 nfs_client_id4 787 struct nfs_client_id4 { 788 verifier4 verifier; 789 opaque id<>; 790 }; 792 This structure is part of the arguments to the SETCLIENTID 793 operation. 795 nfs_lockowner4 797 struct nfs_lockowner4 { 798 clientid4 clientid; 799 opaque owner<>; 800 }; 802 Draft Specification NFS version 4 Protocol January 2000 804 This structure is used to identify the owner of a OPEN share or 805 file lock. 807 Draft Specification NFS version 4 Protocol January 2000 809 3. RPC and Security Flavor 811 The NFS version 4 protocol is a Remote Procedure Call (RPC) 812 application that uses RPC version 2 and the corresponding eXternal 813 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 814 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 815 the mechanism to deliver stronger security for the NFS version 4 816 protocol. 818 3.1. Ports and Transports 820 Historically, NFS version 2 and version 3 servers have resided on 821 port 2049. The registered port 2049 [RFC1700] for the NFS protocol 822 should be the default configuration. Using the registered port for 823 NFS services means the NFS client will not need to use the RPC 824 binding protocols as described in [RFC1833]; this will allow NFS to 825 transit firewalls. 827 The transport used by the RPC service for the NFS version 4 protocol 828 MUST provide congestion control comparable to that defined for TCP in 829 [RFC2581]. If the operating environment implements TCP, the NFS 830 version 4 protocol SHOULD be supported over TCP. The NFS client and 831 server may use other transports if they support congestion control as 832 defined above and in those cases a mechanism may be provided to 833 override TCP usage in favor of another transport. 835 If TCP is used as the transport, the client and server SHOULD use 836 persistent connections. This will prevent the weakening of TCP's 837 congestion control via short lived connections. 839 3.2. Security Flavors 841 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 842 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 843 additional security flavor of RPCSEC_GSS has been introduced which 844 uses the functionality of GSS-API [RFC2078]. This allows for the use 845 of varying security mechanisms by the RPC layer without the 846 additional implementation overhead of adding RPC security flavors. 847 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 848 enable the mandatory security mechanism. Other flavors, such as, 849 AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well. 851 3.2.1. Security mechanisms for NFS version 4 853 The use of RPCSEC_GSS requires selection of: mechanism, quality of 854 protection, and service (authentication, integrity, privacy). The 855 remainder of this document will refer to these three parameters of 857 Draft Specification NFS version 4 Protocol January 2000 859 the RPCSEC_GSS security as the security triple. 861 3.2.1.1. Kerberos V5 as security triple 863 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 864 implemented and provide the following security triples. 866 column descriptions: 868 1 == number of pseudo flavor 869 2 == name of pseudo flavor 870 3 == mechanism's OID 871 4 == mechanism's algorithm(s) 872 5 == RPCSEC_GSS service 874 1 2 3 4 5 875 ----------------------------------------------------------------------- 876 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 877 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 878 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 879 for integrity, 880 and 56 bit DES 881 for privacy. 883 Note that the pseudo flavor is presented here as a mapping aid to the 884 implementor. Because this NFS protocol includes a method to 885 negotiate security and it understands the GSS-API mechanism, the 886 pseudo flavor is not needed. The pseudo flavor is needed for NFS 887 version 3 since the security negotiation is done via the MOUNT 888 protocol. 890 For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please 891 see [RFC2623]. 893 3.2.1.2. LIPKEY as a security triple 895 The LIPKEY GSS-API mechanism as described in [RFCXXXX] MUST be 896 implemented and provide the following security triples. The 897 definition of the columns matches the previous subsection "Kerberos 898 V5 as security triple" 900 1 2 3 4 5 901 ----------------------------------------------------------------------- 902 390006 lipkey TBD negotiated rpc_gss_svc_none 903 390007 lipkey-i TBD negotiated rpc_gss_svc_integrity 904 390008 lipkey-p TBD negotiated rpc_gss_svc_privacy 906 Draft Specification NFS version 4 Protocol January 2000 908 The mechanism algorithm is listed as "negotiated". This is because 909 LIPKEY is layered on SPKM-3 and in SPKM-3 [RFCXXXX] the 910 confidentiality and integrity algorithms are negotiated. Since 911 SPKM-3 specifies HMAC-MD5 for integrity as MANDATORY, 128 bit 912 cast5CBC for confidentiality for privacy as MANDATORY, and further 913 specifies that HMAC-MD5 and cast5CBC MUST be listed first before 914 weaker algorithms, specifying "negotiated" in column 4 does not 915 impair interoperability. In the event an SPKM-3 peer does not 916 support the mandatory algorithms, the other peer is free to accept or 917 reject the GSS-API context creation. 919 Because SPKM-3 negotiates the algorithms, subsequent calls to 920 LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality 921 of protection value of 0 (zero). See section 5.2 of [RFC2025] for an 922 explanation. 924 LIPKEY uses SPKM-3 to create a secure channel in which to pass a user 925 name and password from the client to the user. Once the user name 926 and password have been accepted by the server, calls to the LIPKEY 927 context are redirected to the SPKM-3 context. See [RFCXXXX] for more 928 details. 930 3.2.1.3. SPKM-3 as a security triple 932 The SPKM-3 GSS-API mechanism as described in [RFCXXXX] MUST be 933 implemented and provide the following security triples. The 934 definition of the columns matches the previous subsection "Kerberos 935 V5 as security triple". 937 1 2 3 4 5 938 ----------------------------------------------------------------------- 939 390009 spkm3 TBD negotiated rpc_gss_svc_none 940 390010 spkm3i TBD negotiated rpc_gss_svc_integrity 941 390011 spkm3p TBD negotiated rpc_gss_svc_privacy 943 For a discussion as to why the mechanism algorithm is listed as 944 "negotiated", see the previous section "LIPKEY as a security triple." 946 Because SPKM-3 negotiates the algorithms, subsequent calls to SPKM- 947 3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality of 948 protection value of 0 (zero). See section 5.2 of [RFC2025] for an 949 explanation. 951 Even though LIPKEY is layered onto SPKM-3, SPKM-3 is specified as a 952 mandatory set of triples to handle the situation when the initiator 953 (the client) is anonymous. If the initiator is anonymous, there will 954 not be a user name and password to send to the target (the server). 956 Draft Specification NFS version 4 Protocol January 2000 958 3.3. Security Negotiation 960 With the NFS version 4 server potentially offering multiple security 961 mechanisms, the client needs a method to determine or negotiate which 962 mechanism is to be used for its communication with the server. The 963 NFS server may have multiple points within its file system name space 964 that are available for use by NFS clients. In turn the NFS server 965 may be configured such that each of these entry points may have 966 different or multiple security mechanisms in use. 968 The security negotiation between client and server must be done with 969 a secure channel to eliminate the possibility of a third party 970 intercepting the negotiation sequence and forcing the client and 971 server to choose a lower level of security than required or desired. 973 3.3.1. Security Error 975 Based on the assumption that each NFS version 4 client and server 976 must support a minimum set of security (i.e. LIPKEY, SPKM-3, and 977 Kerberos-V5 all under RPCSEC_GSS), the NFS client will start its 978 communication with the server with one of the minimal security 979 triples. During communication with the server, the client may 980 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 981 server to notify the client that the security triple currently being 982 used is not appropriate for access to the server's file system 983 resources. The client is then responsible for determining what 984 security triples are available at the server and choose one which is 985 appropriate for the client. 987 3.3.2. SECINFO 989 The new SECINFO operation will allow the client to determine, on a 990 per filehandle basis, what security triple is to be used for server 991 access. In general, the client will not have to use the SECINFO 992 procedure except during initial communication with the server or when 993 the client crosses policy boundaries at the server. It is possible 994 that the server's policies change during the client's interaction 995 therefore forcing the client to negotiate a new security triple. 997 3.4. Callback RPC Authentication 999 The callback RPC (described later) must mutually authenticate the NFS 1000 server to the principal that acquired the delegation (also described 1001 later), using the same security flavor the original delegation 1002 operation used. 1004 Draft Specification NFS version 4 Protocol January 2000 1006 For AUTH_NONE, there are no principals, so this is a non-issue. 1008 For AUTH_SYS, the server simply uses the AUTH_SYS credential that the 1009 user used when it set up the delegation. 1011 For AUTH_DH, one commonly used convention is that the server uses the 1012 credentional corresponding to this AUTH_DH principal: 1014 unix.host@domain 1016 where host and domain are variables corresponding to the name of 1017 server host and directory services domain in which it lives such as a 1018 Network Information System domain or a DNS domain. 1020 Regardless of what security mechanism under RPCSEC_GSS is being used, 1021 the NFS server, MUST identify itself in GSS-API via a 1022 GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE 1023 names are of the form: 1025 service@hostname 1027 For NFS, the "service" element is 1029 nfs 1031 Implementations of security mechanisms will convert nfs@hostname to 1032 various different forms. For Kerberos V5 and LIPKEY, the following 1033 form is RECOMMENDED: 1035 nfs/hostname 1037 For Kerberos V5, nfs/hostname would be a server principal in the 1038 Kerberos Key Distribution Center database. For LIPKEY, this would be 1039 the username passed to the target (the NFS version 4 client that 1040 receives the callback). 1042 It should be noted that LIPKEY may not work for callbacks, since the 1043 LIPKEY client uses a user id/password. If the NFS client receiving 1044 the callback can authenticate the NFS server's user name/password 1045 pair, and if the user that the NFS server is authenticating to has a 1046 public key certificiate, then it works. 1048 Draft Specification NFS version 4 Protocol January 2000 1050 4. Filehandles 1052 The filehandle in the NFS protocol is a per server unique identifier 1053 for a file system object. The contents of the filehandle are opaque 1054 to the client. Therefore, the server is responsible for translating 1055 the filehandle to an internal representation of the file system 1056 object. Since the filehandle is the client's reference to an object 1057 and the client may cache this reference, the server should not reuse 1058 a filehandle for another file system object. If the server needs to 1059 reuse a filehandle value, the time elapsed before reuse SHOULD be 1060 large enough that it is likely the client no longer has a cached copy 1061 of the reused filehandle value. 1063 4.1. Obtaining the First Filehandle 1065 The operations of the NFS protocol are defined in terms of one or 1066 more filehandles. Therefore, the client needs a filehandle to 1067 initiate communication with the server. With the NFS version 2 1068 protocol [RFC1094] and the NFS version 3 protocol [RFC1813], there 1069 exists an ancillary protocol to obtain this first filehandle. The 1070 MOUNT protocol, RPC program number 100005, provides the mechanism of 1071 translating a string based file system path name to a filehandle 1072 which can then be used by the NFS protocols. 1074 The MOUNT protocol has deficiencies in the area of security and use 1075 via firewalls. This is one reason that the use of the public 1076 filehandle was introduced in [RFC2054] and [RFC2055]. With the use 1077 of the public filehandle in combination with the LOOKUP procedure in 1078 the NFS version 2 and 3 protocols, it has been demonstrated that the 1079 MOUNT protocol is unnecessary for viable interaction between NFS 1080 client and server. 1082 Therefore, the NFS version 4 protocol will not use an ancillary 1083 protocol for translation from string based path names to a 1084 filehandle. Two special filehandles will be used as starting points 1085 for the NFS client. 1087 4.1.1. Root Filehandle 1089 The first of the special filehandles is the ROOT filehandle. The 1090 ROOT filehandle is the "conceptual" root of the file system name 1091 space at the NFS server. The client uses or starts with the ROOT 1092 filehandle by employing the PUTROOTFH operation. The PUTROOTFH 1093 operation instructs the server to set the "current" filehandle to the 1094 ROOT of the server's file tree. Once this PUTROOTFH operation is 1095 used, the client can then traverse the entirety of the server's file 1097 Draft Specification NFS version 4 Protocol January 2000 1099 tree with the LOOKUP procedure. A complete discussion of the server 1100 name space is in the section "NFS Server Name Space". 1102 4.1.2. Public Filehandle 1104 The second special filehandle is the PUBLIC filehandle. Unlike the 1105 ROOT filehandle, the PUBLIC filehandle may be bound or represent an 1106 arbitrary file system object at the server. The server is 1107 responsible for this binding. It may be that the PUBLIC filehandle 1108 and the ROOT filehandle refer to the same file system object. 1109 However, it is up to the administrative software at the server and 1110 the policies of the server administrator to define the binding of the 1111 PUBLIC filehandle and server file system object. The client may not 1112 make any assumptions about this binding. 1114 4.2. Filehandle Types 1116 In the NFS version 2 and 3 protocols, there was one type of 1117 filehandle with a single set of semantics. The NFS version 4 1118 protocol introduces a new type of filehandle in an attempt to 1119 accommodate certain server environments. The first type of 1120 filehandle is 'persistent'. The semantics of a persistent filehandle 1121 are the same as the filehandles of the NFS version 2 and 3 protocols. 1122 The second or new type of filehandle is the "volatile" filehandle. 1124 The volatile filehandle type is being introduced to address server 1125 functionality or implementation issues which make correct 1126 implementation of a persistent filehandle infeasible. Some server 1127 environments do not provide a file system level invariant that can be 1128 used to construct a persistent filehandle. The underlying server 1129 file system may not provide the invariant or the server's file system 1130 programming interfaces may not provide access to the needed 1131 invariant. Volatile filehandles may ease the implementation of 1132 server functionality such as hierarchical storage management or file 1133 system reorganization or migration. However, the volatile filehandle 1134 increases the implementation burden for the client. However this 1135 increased burden is deemed acceptable based on the overall gains 1136 achieved by the protocol. 1138 Since the client will need to handle persistent and volatile 1139 filehandle differently, a file attribute is defined which may be used 1140 by the client to determine the filehandle types being returned by the 1141 server. 1143 Draft Specification NFS version 4 Protocol January 2000 1145 4.2.1. General Properties of a Filehandle 1147 The filehandle contains all the information the server needs to 1148 distinguish an individual file. To the client, the filehandle is 1149 opaque. The client stores filehandles for use in a later request and 1150 can compare two filehandles from the same server for equality by 1151 doing a byte-by-byte comparison. However, the client MUST NOT 1152 otherwise interpret the contents of filehandles. If two filehandles 1153 from the same server are equal, they MUST refer to the same file. If 1154 they are not equal, the client may use information provided by the 1155 server, in the form of file attributes, to determine whether they 1156 denote the same files or different files. The client would do this 1157 as necessary for client side caching. Servers SHOULD try to maintain 1158 a one-to-one correspondence between filehandles and files but this is 1159 not required. Clients MUST use filehandle comparisons only to 1160 improve performance, not for correct behavior. All clients need to 1161 be prepared for situations in which it cannot be determined whether 1162 two filehandles denote the same object and in such cases, avoid 1163 making invalid assumpions which might cause incorrect behavior. 1164 Further discussion of filehandle and attribute comparison in the 1165 context of data caching is presented in the section "Data Caching and 1166 File Identity". 1168 As an example, in the case that two different path names when 1169 traversed at the server terminate at the same file system object, the 1170 server SHOULD return the same filehandle for each path. This can 1171 occur if a hard link is used to create two file names which refer to 1172 the same underlying file object and associated data. For example, if 1173 paths /a/b/c and /a/d/c refer to the same file, the server SHOULD 1174 return the same filehandle for both path names traversals. 1176 4.2.2. Persistent Filehandle 1178 A persistent filehandle is defined as having a fixed value for the 1179 lifetime of the file system object to which it refers. Once the 1180 server creates the filehandle for a file system object, the server 1181 MUST accept the same filehandle for the object for the lifetime of 1182 the object. If the server restarts or reboots the NFS server must 1183 honor the same filehandle value as it did in the server's previous 1184 instantiation. Similarly, if the file system is migrated, the new 1185 NFS server must honor the same file handle as the old NFS server. 1187 The persistent filehandle will be become stale or invalid when the 1188 file system object is removed. When the server is presented with a 1189 persistent filehandle that refers to a deleted object, it MUST return 1190 an error of NFS4ERR_STALE. A filehandle may become stale when the 1191 file system containing the object is no longer available. The file 1193 Draft Specification NFS version 4 Protocol January 2000 1195 system may become unavailable if it exists on removable media and the 1196 media is no longer available at the server or the file system in 1197 whole has been destroyed or the file system has simply been removed 1198 from the server's name space (i.e. unmounted in a Unix environment). 1200 4.2.3. Volatile Filehandle 1202 A volatile filehandle does not share the same longevity 1203 characteristics of a persistent filehandle. The server may determine 1204 that a volatile filehandle is no longer valid at many different 1205 points in time. If the server can definitively determine that a 1206 volatile filehandle refers to an object that has been removed, the 1207 server should return NFS4ERR_STALE to the client (as is the case for 1208 persistent filehandles). In all other cases where the server 1209 determines that a volatile filehandle can no longer be used, it 1210 should return an error of NFS4ERR_FHEXPIRED. 1212 The mandatory attribute "fh_expire_type" is used by the client to 1213 determine what type of filehandle the server is providing for a 1214 particular file system. This attribute is a bitmask with the 1215 following values: 1217 FH4_PERSISTENT 1218 The value of FH4_PERSISTENT is used to indicate a persistent 1219 filehandle, which is valid until the object is removed from the 1220 file system. The server will not return NFS4ERR_FHEXPIRED for 1221 this filehandle. FH4_PERSISTENT is defined as a value in which 1222 none of the bits specified below are set. 1224 FH4_NOEXPIRE_WITH_OPEN 1225 The filehandle will not expire while client has the file open. 1226 If this bit is set, then the values FH4_VOLATILE_ANY or 1227 FH4_VOL_RENAME do not impact expiration while the file is open. 1228 Once the file is closed or if the FH4_NOEXPIRE_WITH_OPEN bit is 1229 false, the rest of the volatile related bits apply. 1231 FH4_VOLATILE_ANY 1232 The filehandle may expire at any time and will expire on during 1233 system migration. 1235 FH4_VOL_MIGRATION 1236 The filehandle will expire during file system migration and only 1237 then. May only be set if FH4_VOLATILE_ANY is not set. 1239 FH4_VOL_RENAME 1240 The filehandle may expire due to a rename. This includes a 1242 Draft Specification NFS version 4 Protocol January 2000 1244 rename by the requesting client or a rename by another client. 1245 May only be set if FH4_VOLATILE_ANY is not set. 1247 Servers which provide volatile filehandles should deny a RENAME or 1248 REMOVE that would effect an OPEN file or any of the components 1249 leading to the OPEN file. In addition, the server should deny all 1250 RENAME or REMOVE requests during the grace or lease period upon 1251 server restart. 1253 The reader may be wondering why there are three FH4_VOL* bits and why 1254 FH4_VOLATILE_ANY is exclusive of FH4_VOL_MIGRATION and 1255 FH4_VOL_RENAME. If the a filehandle is normally persistent but 1256 cannot persist across a file set migration, then the presence of the 1257 FH4_VOL_MIGRATION or FH4_VOL_RENAME tells the client that it can 1258 treat the file handle as persistent for purposes of maintaining a 1259 file name to file handle cache, except for the specific event 1260 described by the bit. However, FH4_VOLATILE_ANY tells the client 1261 that it should not maintain such a cache for unopened files. A 1262 server MUST not present FH4_VOLATILE_ANY with FH4_VOL_MIGRATION or 1263 FH4_VOL_RENAME as this will lead to confusion. FH4_VOLATILE_ANY 1264 implies that the file handle will expire upon migration or rename, in 1265 addition to other events. 1267 4.2.4. One Method of Constructing a Volatile Filehandle 1269 As mentioned, in some instances a filehandle is stale (no longer 1270 valid; perhaps because the file was removed from the server) or it is 1271 expired (the underlying file is valid but since the filehandle is 1272 volatile, it may have expired). Thus the server needs to be able to 1273 return NFS4ERR_STALE in the former case and NFS4ERR_FHEXPIRED in the 1274 latter case. This can be done by careful construction of the volatile 1275 filehandle. One possible implementation follows. 1277 A volatile filehandle, while opaque to the client could contain: 1279 [volatile bit = 1 | server boot time | slot | generation number] 1281 o slot is an index in the server volatile filehandle table 1283 o generation number is the generation number for the table 1284 entry/slot 1286 If the server boot time is less than the current server boot time, 1287 return NFS4ERR_FHEXPIRED. If slot is out of range, return 1288 NFS4ERR_BADHANDLE. If the generation number does not match, return 1290 Draft Specification NFS version 4 Protocol January 2000 1292 NFS4ERR_FHEXPIRED. 1294 When the server reboots, the table is gone (it is volatile). 1296 If volatile bit is 0, then it is a persistent filehandle with a 1297 different structure following it. 1299 4.3. Client Recovery from Filehandle Expiration 1301 If possible, the client SHOULD recover from the receipt of an 1302 NFS4ERR_FHEXPIRED error. The client must take on additional 1303 responsibility so that it may prepare itself to recover from the 1304 expiration of a volatile filehandle. If the server returns 1305 persistent filehandles, the client does not need these additional 1306 steps. 1308 For volatile filehandles, most commonly the client will need to store 1309 the component names leading up to and including the file system 1310 object in question. With these names, the client should be able to 1311 recover by finding a filehandle in the name space that is still 1312 available or by starting at the root of the server's file system name 1313 space. 1315 If the expired filehandle refers to an object that has been removed 1316 from the file system, obviously the client will not be able to 1317 recover from the expired filehandle. 1319 It is also possible that the expired filehandle refers to a file that 1320 has been renamed. If the file was renamed by another client, again 1321 it is possible that the original client will not be able to recover. 1322 However, in the case that the client itself is renaming the file and 1323 the file is open, it is possible that the client may be able to 1324 recover. The client can determine the new path name based on the 1325 processing of the rename request. The client can then regenerate the 1326 new filehandle based on the new path name. The client could also use 1327 the compound operation mechanism to construct a set of operations 1328 like: 1329 RENAME A B 1330 LOOKUP B 1331 GETFH 1333 Draft Specification NFS version 4 Protocol January 2000 1335 5. File Attributes 1337 To meet the requirements of extensibility and increased 1338 interoperability with non-Unix platforms, attributes must be handled 1339 in a flexible manner. The NFS Version 3 fattr3 structure contains a 1340 fixed list of attributes that not all clients and servers are able to 1341 support or care about. The fattr3 structure can not be extended as 1342 new needs arise and it provides no way to indicate non-support. With 1343 the NFS Version 4 protocol, the client will be able to ask what 1344 attributes the server supports and will be able to request only those 1345 attributes in which it is interested. 1347 To this end, attributes will be divided into three groups: mandatory, 1348 recommended, and named. Both mandatory and recommended attributes 1349 are supported in the NFS version 4 protocol by a specific and well- 1350 defined encoding and are identified by number. They are requested by 1351 setting a bit in the bit vector sent in the GETATTR request; the 1352 server response includes a bit vector to list what attributes were 1353 returned in the response. New mandatory or recommended attributes 1354 may be added to the NFS protocol between major revisions by 1355 publishing a standards-track RFC which allocates a new attribute 1356 number value and defines the encoding for the attribute. See the 1357 section "Minor Versioning" for further discussion. 1359 Named attributes are accessed by the new OPENATTR operation, which 1360 accesses a hidden directory of attributes associated with a file 1361 system object. OPENATTR takes a filehandle for the object and 1362 returns the filehandle for the attribute hierarchy. The filehandle 1363 for the named attributes is a directory object accessible by LOOKUP 1364 or READDIR and contains files whose names represent the named 1365 attributes and whose data bytes are the value of the attribute. For 1366 example: 1368 LOOKUP "foo" ; look up file 1369 GETATTR attrbits 1370 OPENATTR ; access foo's named attributes 1371 LOOKUP "x11icon" ; look up specific attribute 1372 READ 0,4096 ; read stream of bytes 1374 Named attributes are intended for data needed by applications rather 1375 than by an NFS client implementation. NFS implementors are strongly 1376 encouraged to define their new attributes as recommended attributes 1377 by bringing them to the IETF standards-track process. 1379 The set of attributes which are classified as mandatory is 1380 deliberately small since servers must do whatever it takes to support 1382 Draft Specification NFS version 4 Protocol January 2000 1384 them. The recommended attributes may be unsupported; though a server 1385 should support as many as it can. Attributes are deemed mandatory if 1386 the data is both needed by a large number of clients and is not 1387 otherwise reasonably computable by the client when support is not 1388 provided on the server. 1390 5.1. Mandatory Attributes 1392 These MUST be supported by every NFS Version 4 client and server in 1393 order to ensure a minimum level of interoperability. The server must 1394 store and return these attributes and the client must be able to 1395 function with an attribute set limited to these attributes. With 1396 just the mandatory attributes some client functionality may be 1397 impaired or limited in some ways. A client may ask for any of these 1398 attributes to be returned by setting a bit in the GETATTR request and 1399 the server must return their value. 1401 5.2. Recommended Attributes 1403 These attributes are understood well enough to warrant support in the 1404 NFS Version 4 protocol. However, they may not be supported on all 1405 clients and servers. A client may ask for any of these attributes to 1406 be returned by setting a bit in the GETATTR request but must handle 1407 the case where the server does not return them. A client may ask for 1408 the set of attributes the server supports and should not request 1409 attributes the server does not support. A server should be tolerant 1410 of requests for unsupported attributes and simply not return them 1411 rather than considering the request an error. It is expected that 1412 servers will support all attributes they comfortably can and only 1413 fail to support attributes which are difficult to support in their 1414 operating environments. A server should provide attributes whenever 1415 they don't have to "tell lies" to the client. For example, a file 1416 modification time should be either an accurate time or should not be 1417 supported by the server. This will not always be comfortable to 1418 clients but it seems that the client has a better ability to 1419 fabricate or construct an attribute or do without the attribute. 1421 5.3. Named Attributes 1423 These attributes are not supported by direct encoding in the NFS 1424 Version 4 protocol but are accessed by string names rather than 1425 numbers and correspond to an uninterpreted stream of bytes which are 1426 stored with the file system object. The name space for these 1427 attributes may be accessed by using the OPENATTR operation. The 1428 OPENATTR operation returns a filehandle for a virtual "attribute 1430 Draft Specification NFS version 4 Protocol January 2000 1432 directory" and further perusal of the name space may be done using 1433 READDIR and LOOKUP operations on this filehandle. Named attributes 1434 may then be examined or changed by normal READ and WRITE and CREATE 1435 operations on the filehandles returned from READDIR and LOOKUP. 1436 Named attributes may have attributes. 1438 It is recommended that servers support arbitrary named attributes. A 1439 client should not depend on the ability to store any named attributes 1440 in the server's file system. If a server does support named 1441 attributes, a client which is also able to handle them should be able 1442 to copy a file's data and meta-data with complete transparency from 1443 one location to another; this would imply that names allowed for 1444 regular directory entries are valid for named attribute names as 1445 well. 1447 Names of attributes will not be controlled by this document or other 1448 IETF standards track documents. See the section "IANA 1449 Considerations" for further discussion. 1451 Draft Specification NFS version 4 Protocol January 2000 1453 5.4. Mandatory Attributes - Definitions 1455 Name # DataType Access Description 1456 ___________________________________________________________________ 1457 supp_attr 0 bitmap READ The bit vector which 1458 would retrieve all 1459 mandatory and 1460 recommended attributes 1461 that are supported for 1462 this object. 1464 object_type 1 nfs4_ftype READ The type of the object 1465 (file, directory, 1466 symlink) 1468 fh_expire_type 2 uint32 READ Server uses this to 1469 specify filehandle 1470 expiration behavior to 1471 the client. See the 1472 section "Filehandles" 1473 for additional 1474 description. 1476 change 3 uint64 READ A value created by the 1477 server that the client 1478 can use to determine 1479 if file data, 1480 directory contents or 1481 attributes of the 1482 object have been 1483 modified. The server 1484 may return the 1485 object's time_modify 1486 attribute for this 1487 attribute's value but 1488 only if the file 1489 system object can not 1490 be updated more 1491 frequently than the 1492 resolution of 1493 time_modify. 1495 object_size 4 uint64 R/W The size of the object 1496 in bytes. 1498 Draft Specification NFS version 4 Protocol January 2000 1500 link_support 5 boolean READ Does the object's file 1501 system supports hard 1502 links? 1504 symlink_support 6 boolean READ Does the object's file 1505 system supports 1506 symbolic links? 1508 named_attr 7 boolean READ Does this object have 1509 named attributes? 1511 fsid 8 fsid4 READ Unique file system 1512 identifier for the 1513 file system holding 1514 this object. fsid 1515 contains major and 1516 minor components each 1517 of which are uint64. 1519 unique_handles 9 boolean READ Are two distinct 1520 filehandles guaranteed 1521 to refer to two 1522 different file system 1523 objects? 1525 lease_time 10 nfs_lease4 READ Duration of leases at 1526 server in seconds. 1528 rdattr_error 11 enum READ Error returned from 1529 getattr during 1530 readdir. 1532 Draft Specification NFS version 4 Protocol January 2000 1534 5.5. Recommended Attributes - Definitions 1536 Name # Data Type Access Description 1537 _____________________________________________________________________ 1538 ACL 12 nfsace4<> R/W The access control 1539 list for the object. 1541 aclsupport 13 uint32 READ Indicates what types 1542 of ACLs are supported 1543 on the current file 1544 system. 1546 archive 14 boolean R/W Whether or not this 1547 file has been 1548 archived since the 1549 time of last 1550 modification 1551 (deprecated in favor 1552 of backup_time). 1554 cansettime 15 boolean READ Whether or not this 1555 object's file system 1556 can fill in the times 1557 on a SETATTR request 1558 without an explicit 1559 time. 1561 case_insensitive 16 boolean READ Are filename 1562 comparisons on this 1563 file system case 1564 insensitive? 1566 case_preserving 17 boolean READ Is filename case on 1567 this file system 1568 preserved? 1570 Draft Specification NFS version 4 Protocol January 2000 1572 chown_restricted 18 boolean READ If TRUE, the server 1573 will reject any 1574 request to change 1575 either the owner or 1576 the group associated 1577 with a file if the 1578 caller is not a 1579 privileged user (for 1580 example, "root" in 1581 Unix operating 1582 environments or in NT 1583 the "Take Ownership" 1584 privilege) 1586 filehandle 19 nfs4_fh READ The filehandle of 1587 this object 1588 (primarily for 1589 readdir requests). 1591 fileid 20 uint64 READ A number uniquely 1592 identifying the file 1593 within the file 1594 system. 1596 files_avail 21 uint64 READ File slots available 1597 to this user on the 1598 file system 1599 containing this 1600 object - this should 1601 be the smallest 1602 relevant limit. 1604 files_free 22 uint64 READ Free file slots on 1605 the file system 1606 containing this 1607 object - this should 1608 be the smallest 1609 relevant limit. 1611 files_total 23 uint64 READ Total file slots on 1612 the file system 1613 containing this 1614 object. 1616 Draft Specification NFS version 4 Protocol January 2000 1618 fs_locations 24 fs_locations READ Locations where this 1619 file system may be 1620 found. If the server 1621 returns NFS4ERR_MOVED 1622 as an error, this 1623 attribute must be 1624 supported. 1626 hidden 25 boolean R/W Is file considered 1627 hidden with respect 1628 to the WIN32 API? 1630 homogeneous 26 boolean READ Whether or not this 1631 object's file system 1632 is homogeneous, i.e. 1633 whether pathconf is 1634 the same for all file 1635 system objects. 1637 maxfilesize 27 uint64 READ Maximum supported 1638 file size for the 1639 file system of this 1640 object. 1642 maxlink 28 uint32 READ Maximum number of 1643 links for this 1644 object. 1646 maxname 29 uint32 READ Maximum filename size 1647 supported for this 1648 object. 1650 maxread 30 uint64 READ Maximum read size 1651 supported for this 1652 object. 1654 Draft Specification NFS version 4 Protocol January 2000 1656 maxwrite 31 uint64 READ Maximum write size 1657 supported for this 1658 object. This 1659 attribute SHOULD be 1660 supported if the file 1661 is writable. Lack of 1662 this attribute can 1663 lead to the client 1664 either wasting 1665 bandwidth or not 1666 receiving the best 1667 performance. 1669 mime_type 32 utf8<> R/W MIME body 1670 type/subtype of this 1671 object. 1673 mode 33 mode4 R/W Unix-style permission 1674 bits for this object 1675 (deprecated in favor 1676 of ACLs) 1678 no_trunc 34 boolean READ If a name longer than 1679 name_max is used, 1680 will an error be 1681 returned or will the 1682 name be truncated? 1684 numlinks 35 uint32 READ Number of links to 1685 this object. 1687 owner 36 utf8<> R/W The string name of 1688 the owner of this 1689 object. 1691 owner_group 37 utf8<> R/W The string name of 1692 the group of the 1693 owner of this object. 1695 quota_hard 38 uint64 READ For definition see 1696 "Quota Attributes" 1697 section below. 1699 quota_soft 39 uint64 READ For definition see 1700 "Quota Attributes" 1701 section below. 1703 Draft Specification NFS version 4 Protocol January 2000 1705 quota_used 40 uint64 READ For definition see 1706 "Quota Attributes" 1707 section below. 1709 rawdev 41 specdata4 READ Raw device 1710 identifier. 1712 space_avail 42 uint64 READ Disk space in bytes 1713 available to this 1714 user on the file 1715 system containing 1716 this object - this 1717 should be the 1718 smallest relevant 1719 limit. 1721 space_free 43 uint64 READ Free disk space in 1722 bytes on the file 1723 system containing 1724 this object - this 1725 should be the 1726 smallest relevant 1727 limit. 1729 space_total 44 uint64 READ Total disk space in 1730 bytes on the file 1731 system containing 1732 this object. 1734 space_used 45 uint64 READ Number of file system 1735 bytes allocated to 1736 this object. 1738 system 46 boolean R/W Is this file is a 1739 system file with 1740 respect to the WIN32 1741 API? 1743 time_access 47 nfstime4 R/W The time of last 1744 access to the object. 1746 time_backup 48 nfstime4 R/W The time of last 1747 backup of the object. 1749 Draft Specification NFS version 4 Protocol January 2000 1751 time_create 49 nfstime4 R/W The time of creation 1752 of the object. This 1753 attribute does not 1754 have any relation to 1755 the traditional Unix 1756 file attribute 1757 "ctime" or "change 1758 time". 1760 time_delta 50 nfstime4 READ Smallest useful 1761 server time 1762 granularity. 1764 time_metadata 51 nfstime4 R/W The time of last 1765 meta-data 1766 modification of the 1767 object. 1769 time_modify 52 nfstime4 R/W The time of last 1770 modification to the 1771 object. 1773 5.6. Interpreting owner and owner_group 1775 The recommended attributes "owner" and "owner_group" are represented 1776 in terms of a UTF-8 string. To avoid a representation that is tied 1777 to a particular underlying implementation at the client or server, 1778 the use of the UTF-8 string has been chosen. Note that section 6.1 1779 of [RFC2624] provides additional rationale. It is expected that the 1780 client and server will have their own local representation of owner 1781 and owner_group that is used for local storage or presentation to the 1782 end user. Therefore, it is expected that when these attributes are 1783 transferred between the client and server that the local 1784 representation is translated to a syntax of the form 1785 "user@dns_domain". This will allow for a client and server that do 1786 not use the same local representation the ability to translate to a 1787 common syntax that can be interpreted by both. 1789 The translation is not specified as part of the protocol. This 1790 allows various solutions to be employed. For example, a local 1791 translation table may be consulted that maps between a numeric id to 1792 the user@dns_domain syntax. A name service may also be used to 1793 accomplish the translation. The "dns_domain" portion of the owner 1794 string is meant to be a DNS domain name. For example, user@ietf.org. 1796 Draft Specification NFS version 4 Protocol January 2000 1798 In the case where there is no translation available to the client or 1799 server, the attribute value must be constructed without the "@". 1800 Therefore, the absence of the @ from the owner or owner_group 1801 attribute signifies that no translation was available and the 1802 receiver of the attribute should not place any special meaning with 1803 the attribute value. Even though the attribute value can not be 1804 translated, it may still be useful. In the case of a client, the 1805 attribute string may be used for local display of ownership. 1807 5.7. Quota Attributes 1809 For the attributes related to file system quotas, the following 1810 definitions apply: 1812 quota_avail_soft 1813 The value in bytes which represents the amount of additional 1814 disk space that can be allocated to this file or directory 1815 before the user may reasonably be warned. It is understood that 1816 this space may be consumed by allocations to other files or 1817 directories though there is a rule as to which other files or 1818 directories. 1820 quota_avail_hard 1821 The value in bytes which represent the amount of additional disk 1822 space beyond the current allocation that can be allocated to 1823 this file or directory before further allocations will be 1824 declined. It is understood that this space may be consumed by 1825 allocations to other files or directories. 1827 quota_used 1828 The value in bytes which represent the amount of disc space used 1829 by this file or directory and possibly a number of other similar 1830 files or directories, where the set of "similar" meets at least 1831 the criterion that allocating space to any file or directory in 1832 the set will reduce the "quota_avail_hard" of every other file 1833 or directory in the set. 1835 Note that there may be a number of distinct but overlapping sets 1836 of files or directories for which a quota_used value is 1837 maintained. E.g. "all files with a given owner", "all files with 1838 a given group owner". etc. 1840 The server is at liberty to choose any of those sets but should 1841 do so in a repeatable way. The rule may be configured per- 1842 filesystem or may be "choose the set with the smallest quota". 1844 Draft Specification NFS version 4 Protocol January 2000 1846 5.8. Access Control Lists 1848 The NFS ACL attribute is an array of access control entries (ACE). 1849 There are various access control entry types. The server is able to 1850 communicate which ACE types are supported by returning the 1851 appropriate value within the aclsupport attribute. The types of ACEs 1852 are defined as follows: 1854 Type Description 1855 _____________________________________________________ 1856 ALLOW Explicitly grants the access defined in 1857 acemask4 to the file or directory. 1859 DENY Explicitly denies the access defined in 1860 acemask4 to the file or directory. 1862 AUDIT LOG (system dependant) any access 1863 attempt to a file or directory which 1864 uses any of the access methods specified 1865 in acemask4. 1867 ALARM Generate a system ALARM (system 1868 dependant) when any access attempt is 1869 made to a file or directory for the 1870 access methods specified in acemask4. 1872 The NFS ACE attribute is defined as follows: 1874 typedef uint32_t acetype4; 1875 typedef uint32_t aceflag4; 1876 typedef uint32_t acemask4; 1878 struct nfsace4 { 1879 acetype4 type; 1880 aceflag4 flag; 1881 acemask4 access_mask; 1882 utf8string who; 1883 }; 1885 To determine if an ACCESS or OPEN request succeeds each nfsace4 entry 1886 is processed in order by the server. Only ACEs which have a "who" 1887 that matches the requester are considered. Each ACE is processed 1888 until all of the bits of the requester's access have been ALLOWED. 1889 Once a bit (see below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it 1890 is no longer considered in the processing of later ACEs. If an 1891 ACCESS_DENIED_ACE is encountered where the requester's mode still has 1892 unALLOWED bits in common with the "access_mask" of the ACE, the 1893 request is denied. 1895 Draft Specification NFS version 4 Protocol January 2000 1897 The bitmask constants used to represent the above definitions within 1898 the aclsupport attribute are as follows: 1900 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 1901 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 1902 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 1903 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 1905 5.8.1. ACE type 1907 The semantics of the "type" field follow the descriptions provided 1908 above. 1910 The bitmask constants used to for the type field are as follows: 1912 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 1913 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 1914 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 1915 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 1917 5.8.2. ACE flag 1919 The "flag" field contains values based on the following descriptions. 1921 ACE4_FILE_INHERIT_ACE 1923 Can be placed on a directory and indicates that this ACE should be 1924 added to each new non-directory file created. 1926 ACE4_DIRECTORY_INHERIT_ACE 1928 Can be placed on a directory and indicates that this ACE should be 1929 added to each new directory created. 1931 ACE4_INHERIT_ONLY_ACE 1933 Can be placed on a directory but does not apply to the directory, 1934 only to newly created files/directories as specified by the above two 1935 flags. 1937 ACE4_NO_PROPAGATE_INHERIT_ACE 1939 Draft Specification NFS version 4 Protocol January 2000 1941 Can be placed on a directory. Normally when a new directory is 1942 created and an ACE exists on the parent directory which is marked 1943 ACL4_DIRECTORY_INHERIT_ACE, two ACEs are placed on the new directory. 1944 One for the directory itself and one which is an inheritable ACE for 1945 newly created directories. This flag tells the server to not place 1946 an ACE on the newly created directory which is inheritable by 1947 subdirectories of the created directory. 1949 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 1951 ACL4_FAILED_ACCESS_ACE_FLAG 1953 Both indicate for AUDIT and ALARM which state to log the event. On 1954 every ACCESS or OPEN call which occurs on a file or directory which 1955 has an ACL that is of type ACE4_SYSTEM_AUDIT_ACE_TYPE or 1956 ACE4_SYSTEM_ALARM_ACE_TYPE, the attempted access is compared to the 1957 ace4mask of these ACLs. If the access is a subset of ace4mask and the 1958 identifier match, an AUDIT trail or an ALARM is generated. By 1959 default this happens regardless of the success or failure of the 1960 ACCESS or OPEN call. 1962 The flag ACE4_SUCCESSFUL_ACCESS_ACE_FLAG only produces the AUDIT or 1963 ALARM if the ACCESS or OPEN call is successful. The 1964 ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS 1965 or OPEN call fails. 1967 ACE4_IDENTIFIER_GROUP 1969 Indicates that the "who" refers to a GROUP as defined under Unix. 1971 The bitmask constants used to for the flag field are as follows: 1973 const ACE4_FILE_INHERIT_ACE = 0x00000001; 1974 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 1975 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 1976 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 1977 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 1978 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 1979 const ACE4_IDENTIFIER_GROUP = 0x00000040; 1981 5.8.3. ACE Access Mask 1983 The access_mask field contains values based on the following: 1985 Draft Specification NFS version 4 Protocol January 2000 1987 Access Description 1988 _______________________________________________________________ 1989 READ_DATA Permission to read the data of the file 1990 LIST_DIRECTORY Permission to list the contents of a 1991 directory 1992 WRITE_DATA Permission to modify the file's data 1993 ADD_FILE Permission to add a new file to a 1994 directory 1995 APPEND_DATA Permission to append data to a file 1996 ADD_SUBDIRECTORY Permission to create a subdirectory to a 1997 directory 1998 READ_NAMED_ATTRS Permission to read the named attributes 1999 of a file 2000 WRITE_NAMED_ATTRS Permission to write the named attributes 2001 of a file 2002 EXECUTE Permission to execute a file 2003 DELETE_CHILD Permission to delete a file or directory 2004 within a directory 2005 READ_ATTRIBUTES The ability to read basic attributes 2006 (non-acls) of a file 2007 WRITE_ATTRIBUTES Permission to change basic attributes 2008 (non-acls) of a file 2010 DELETE Permission to Delete the File 2011 READ_ACL Permission to Read the ACL 2012 WRITE_ACL Permission to Write the ACL 2013 WRITE_OWNER Permission to change the owner 2014 SYNCHRONIZE Permission to access file locally at the 2015 server with synchronous reads and writes 2017 The bitmask constants used to for the access mask field are as 2018 follows: 2020 const ACE4_READ_DATA = 0x00000001; 2021 const ACE4_LIST_DIRECTORY = 0x00000001; 2022 const ACE4_WRITE_DATA = 0x00000002; 2023 const ACE4_ADD_FILE = 0x00000002; 2024 const ACE4_APPEND_DATA = 0x00000004; 2025 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 2026 const ACE4_READ_NAMED_ATTRS = 0x00000008; 2027 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 2028 const ACE4_EXECUTE = 0x00000020; 2029 const ACE4_DELETE_CHILD = 0x00000040; 2030 const ACE4_READ_ATTRIBUTES = 0x00000080; 2031 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 2033 const ACE4_DELETE = 0x00010000; 2034 const ACE4_READ_ACL = 0x00020000; 2036 Draft Specification NFS version 4 Protocol January 2000 2038 const ACE4_WRITE_ACL = 0x00040000; 2039 const ACE4_WRITE_OWNER = 0x00080000; 2040 const ACE4_SYNCHRONIZE = 0x00100000; 2042 5.8.4. ACE who 2044 There are several special identifiers ("who") which need to be 2045 understood universally. Some of these identifiers cannot be 2046 understood when an NFS client accesses the server, but have meaning 2047 when a local process accesses the file. The ability to display and 2048 modify these permissions is permitted over NFS. 2050 Who Description 2051 _______________________________________________________________ 2052 "OWNER" The owner of the file. 2053 "GROUP" The group associated with the file. 2054 "EVERYONE" The world. 2055 "INTERACTIVE" Accessed from an interactive terminal. 2056 "NETWORK" Accessed via the network. 2057 "DIALUP" Accessed as a dialup user to the server. 2058 "BATCH" Accessed from a batch job. 2059 "ANONYMOUS" Accessed without any authentication. 2060 "AUTHENTICATED" Any authenticated user (opposite of 2061 ANONYMOUS) 2062 "SERVICE" Access from a system service. 2064 To avoid conflict, these special identitifers are distinguish by an 2065 appended "@" and should appear in the form "xxxx@" (note: no domain 2066 name after the "@"). For example: ANONYMOUS@. 2068 Draft Specification NFS version 4 Protocol January 2000 2070 6. File System Migration and Replication 2072 With the use of the recommended attribute "fs_locations", the NFS 2073 version 4 server has a method of providing file system migration or 2074 replication services. For the purposes of migration and replication, 2075 a file system will be defined as all files that share a given fsid 2076 (both major and minor values are the same). 2078 The fs_locations attribute provides a list of file system locations. 2079 These locations are specified by providing the server name (either 2080 DNS domain or IP address) and the path name representing the root of 2081 the file system. Depending on the type of service being provided, 2082 the list will provide a new location or a set of alternate locations 2083 for the file system. The client will use this information to 2084 redirect its requests to the new server. 2086 6.1. Replication 2088 It is expected that file system replication will be used in the case 2089 of read-only data. Typically, the file system will be replicated on 2090 two or more servers. The fs_locations attribute will provide the 2091 list of these locations to the client. On first access of the file 2092 system, the client should obtain the value of the fs_locations 2093 attribute. If, in the future, the client finds the server 2094 unresponsive, the client may attempt to use another server specified 2095 by fs_locations. 2097 If applicable, the client must take the appropriate steps to recover 2098 valid filehandles from the new server. This is described in more 2099 detail in the following sections. 2101 6.2. Migration 2103 File system migration is used to move a file system from one server 2104 to another. Migration is typically used for a file system that is 2105 writable and has a single copy. The expected use of migration is for 2106 load balancing or general resource reallocation. The protocol does 2107 not specify how the file system will be moved between servers. This 2108 server-to-server transfer mechanism is left to the server 2109 implementor. However, the method used to communicate the migration 2110 event between client and server is specified here. 2112 Once the servers participating in the migration have completed the 2113 move of the file system, the error NFS4ERR_MOVED will be returned for 2114 subsequent requests received by the original server. The 2115 NFS4ERR_MOVED error is returned for all operations except GETATTR. 2117 Draft Specification NFS version 4 Protocol January 2000 2119 Upon receiving the NFS4ERR_MOVED error, the client will obtain the 2120 value of the fs_locations attribute. The client will then use the 2121 contents of the attribute to redirect its requests to the specified 2122 server. To facilitate the use of GETATTR, operations such as PUTFH 2123 must also be accepted by the server for the migrated file system's 2124 filehandles. Note that if the server returns NFS4ERR_MOVED, the 2125 server MUST support the fs_locations attribute. 2127 If the client requests more attributes than fs_locations, the server 2128 may return fs_locations only. This is to be expected since the 2129 server has migrated the file system and may not have a method of 2130 obtaining additional attribute data. 2132 The server implementor needs to be careful in developing a migration 2133 solution. The server must consider all of the state information 2134 clients may have outstanding at the server. This includes but is not 2135 limited to locking/share state, delegation state, and asynchronous 2136 file writes which are represented by WRITE and COMMIT verifiers. The 2137 server should strive to minimize the impact on its clients during and 2138 after the migration process. 2140 6.3. Interpretation of the fs_locations Attribute 2142 The fs_location attribute is structured in the following way: 2144 struct fs_location { 2145 utf8string server<>; 2146 pathname4 rootpath; 2147 }; 2149 struct fs_locations { 2150 pathname4 fs_root; 2151 fs_location locations<>; 2152 }; 2154 The fs_location struct is used to represent the location of a file 2155 system by providing a server name and the path to the root of the 2156 file system. For a multi-homed server or a set of servers that use 2157 the same rootpath, an array of server names may be provided. An 2158 entry in the server array is an UTF8 string and represents one of a 2159 traditional DNS host name, IPv4 address, or IPv6 address. It is not 2160 a requirement that all servers that share the same rootpath be listed 2161 in one fs_location struct. The array of server names is provided for 2162 convenience. Servers that share the same rootpath may also be listed 2163 in separate fs_location entries in the fs_locations attribute. 2165 The fs_locations struct and attribute then contains an array of 2167 Draft Specification NFS version 4 Protocol January 2000 2169 locations. Since the name space of each server may be constructed 2170 differently, the "fs_root" field is provided. The path represented 2171 by fs_root represents the location of the file system in the server's 2172 name space. Therefore, the fs_root path is only associated with the 2173 server from which the fs_locations attribute was obtained. The 2174 fs_root path is meant to aid the client in locating the file system 2175 at the various servers listed. 2177 As an example, there is a replicated file system located at two 2178 servers (servA and servB). At servA the file system is located at 2179 path "/a/b/c". At servB the file system is located at path "/x/y/z". 2180 In this example the client accesses the file system first at servA 2181 with a multi-component lookup path of "/a/b/c/d". Since the client 2182 used a multi-component lookup to obtain the filehandle at "/a/b/c/d", 2183 it is unaware that the file system's root is located in servA's name 2184 space at "/a/b/c". When the client switches to servB, it will need 2185 to determine that the directory it first referenced at servA is now 2186 represented by the path "/x/y/z/d" on servB. To facilitate this, the 2187 fs_locations attribute provided by servA would have a fs_root value 2188 of "/a/b/c" and two entries in fs_location. One entry in fs_location 2189 will be for itself (servA) and the other will be for servB with a 2190 path of "/x/y/z". With this information, the client is able to 2191 substitute "/x/y/z" for the "/a/b/c" at the beginning of its access 2192 path and construct "/x/y/z/d" to use for the new server. 2194 6.4. Filehandle Recovery for Migration or Replication 2196 Filehandles for file systems that are replicated or migrated 2197 generally have the same semantics as for file systems that are not 2198 replicated or migrated. For example, if a file system has persistent 2199 filehandles and it is migrated to another server, the filehandle 2200 values for the file system will be valid at the new server. 2202 For volatile filehandles, the servers involved likely do not have a 2203 mechanism to transfer filehandle format and content between 2204 themselves. Therefore, a server may have difficulty in determining 2205 if a volatile filehandle from an old server should return an error of 2206 NFS4ERR_FHEXPIRED. Therefore, the client is informed, with the use 2207 of the fh_expire_type attribute, whether volatile filehandles will 2208 expire at the migration or replication event. If the bit 2209 FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client 2210 must treat the volatile filehandle as if the server had returned the 2211 NFS4ERR_FHEXPIRED error. At the migration or replication event in 2212 the presence of the FH4_VOL_MIGRATION bit, the client will not 2213 present the original or old volatile file handle to the new server. 2214 The client will start its communication with the new server by 2215 recovering its filehandles using the saved file names. 2217 Draft Specification NFS version 4 Protocol January 2000 2219 7. NFS Server Name Space 2221 7.1. Server Exports 2223 On a UNIX server the name space describes all the files reachable by 2224 pathnames under the root directory or "/". On a Windows NT server 2225 the name space constitutes all the files on disks named by mapped 2226 disk letters. NFS server administrators rarely make the entire 2227 server's file system name space available to NFS clients. More often 2228 portions of the name space are made available via an "export" 2229 feature. In previous versions of the NFS protocol, the root 2230 filehandle for each export is obtained through the MOUNT protocol; 2231 the client sends a string that identifies the export of name space 2232 and the server returns the root filehandle for it. The MOUNT 2233 protocol supports an EXPORTS procedure that will enumerate the 2234 server's exports. 2236 7.2. Browsing Exports 2238 The NFS version 4 protocol provides a root filehandle that clients 2239 can use to obtain filehandles for these exports via a multi-component 2240 LOOKUP. A common user experience is to use a graphical user 2241 interface (perhaps a file "Open" dialog window) to find a file via 2242 progressive browsing through a directory tree. The client must be 2243 able to move from one export to another export via single-component, 2244 progressive LOOKUP operations. 2246 This style of browsing is not well supported by the NFS version 2 and 2247 3 protocols. The client expects all LOOKUP operations to remain 2248 within a single server file system. For example, the device 2249 attribute will not change. This prevents a client from taking name 2250 space paths that span exports. 2252 An automounter on the client can obtain a snapshot of the server's 2253 name space using the EXPORTS procedure of the MOUNT protocol. If it 2254 understands the server's pathname syntax, it can create an image of 2255 the server's name space on the client. The parts of the name space 2256 that are not exported by the server are filled in with a "pseudo file 2257 system" that allows the user to browse from one mounted file system 2258 to another. There is a drawback to this representation of the 2259 server's name space on the client: it is static. If the server 2260 administrator adds a new export the client will be unaware of it. 2262 Draft Specification NFS version 4 Protocol January 2000 2264 7.3. Server Pseudo File System 2266 NFS version 4 servers avoid this name space inconsistency by 2267 presenting all the exports within the framework of a single server 2268 name space. An NFS version 4 client uses LOOKUP and READDIR 2269 operations to browse seamlessly from one export to another. Portions 2270 of the server name space that are not exported are bridged via a 2271 "pseudo file system" that provides a view of exported directories 2272 only. A pseudo file system has a unique fsid and behaves like a 2273 normal, read only file system. 2275 Based on the construction of the server's name space, it is possible 2276 that multiple pseudo file systems may exist. For example, 2278 /a pseudo file system 2279 /a/b real file system 2280 /a/b/c pseudo file system 2281 /a/b/c/d real file system 2283 Each of the pseudo file systems are consider separate entities and 2284 therefore will have a unique fsid. 2286 7.4. Multiple Roots 2288 The DOS and Windows operating environments are sometimes described as 2289 having "multiple roots". File systems are commonly represented as 2290 disk letters. MacOS represents file systems as top level names. NFS 2291 version 4 servers for these platforms can construct a pseudo file 2292 system above these root names so that disk letters or volume names 2293 are simply directory names in the pseudo root. 2295 7.5. Filehandle Volatility 2297 The nature of the server's pseudo file system is that it is a logical 2298 representation of file system(s) available from the server. 2299 Therefore, the pseudo file system is most likely constructed 2300 dynamically when the server is first instantiated. It is expected 2301 that the pseudo file system may not have an on disk counterpart from 2302 which persistent filehandles could be constructed. Even though it is 2303 preferable that the server provide persistent filehandles for the 2304 pseudo file system, the NFS client should expect that pseudo file 2305 system filehandles are volatile. This can be confirmed by checking 2306 the associated "persistent_fh" attribute for those filehandles in 2307 question. If the filehandles are volatile, the NFS client must be 2308 prepared to recover a filehandle value (e.g. with a multi-component 2309 LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 2311 Draft Specification NFS version 4 Protocol January 2000 2313 7.6. Exported Root 2315 If the server's root file system is exported, one might conclude that 2316 a pseudo-file system is not needed. This would be wrong. Assume the 2317 following file systems on a server: 2319 / disk1 (exported) 2320 /a disk2 (not exported) 2321 /a/b disk3 (exported) 2323 Because disk2 is not exported, disk3 cannot be reached with simple 2324 LOOKUPs. The server must bridge the gap with a pseudo-file system. 2326 7.7. Mount Point Crossing 2328 The server file system environment may be constructed in such a way 2329 that one file system contains a directory which is 'covered' or 2330 mounted upon by a second file system. For example: 2332 /a/b (file system 1) 2333 /a/b/c/d (file system 2) 2335 The pseudo file system for this server may be constructed to look 2336 like: 2338 / (place holder/not exported) 2339 /a/b (file system 1) 2340 /a/b/c/d (file system 2) 2342 It is the server's responsibility to present the pseudo file system 2343 that is complete to the client. If the client sends a lookup request 2344 for the path "/a/b/c/d", the server's response is the filehandle of 2345 the file system "/a/b/c/d". In previous versions of the NFS 2346 protocol, the server would respond with the directory "/a/b/c/d" 2347 within the file system "/a/b". 2349 The NFS client will be able to determine if it crosses a server mount 2350 point by a change in the value of the "fsid" attribute. 2352 7.8. Security Policy and Name Space Presentation 2354 The application of the server's security policy needs to be carefully 2355 considered by the implementor. One may choose to limit the 2356 viewability of portions of the pseudo file system based on the 2357 server's perception of the client's ability to authenticate itself 2358 properly. However with the support of multiple security mechanisms 2360 Draft Specification NFS version 4 Protocol January 2000 2362 and the ability to negotiate the appropriate use of these mechanisms, 2363 the server is unable to properly determine if a client will be able 2364 to authenticate itself. If, based on its policies, the server 2365 chooses to limit the contents of the pseudo file system, the server 2366 may effectively hide file systems from a client that may otherwise 2367 have legitimate access. 2369 Draft Specification NFS version 4 Protocol January 2000 2371 8. File Locking and Share Reservations 2373 Integrating locking into the NFS protocol necessarily causes it to be 2374 state-full. With the inclusion of "share" file locks the protocol 2375 becomes substantially more dependent on state than the traditional 2376 combination of NFS and NLM [XNFS]. There are three components to 2377 making this state manageable: 2379 o Clear division between client and server 2381 o Ability to reliably detect inconsistency in state between client 2382 and server 2384 o Simple and robust recovery mechanisms 2386 In this model, the server owns the state information. The client 2387 communicates its view of this state to the server as needed. The 2388 client is also able to detect inconsistent state before modifying a 2389 file. 2391 To support Win32 "share" locks it is necessary to atomically OPEN or 2392 CREATE files. Having a separate share/unshare operation would not 2393 allow correct implementation of the Win32 OpenFile API. In order to 2394 correctly implement share semantics, the previous NFS protocol 2395 mechanisms used when a file is opened or created (LOOKUP, CREATE, 2396 ACCESS) need to be replaced. The NFS version 4 protocol has an OPEN 2397 operation that subsumes the functionality of LOOKUP, CREATE, and 2398 ACCESS. However, because many operations require a filehandle, the 2399 traditional LOOKUP is preserved to map a file name to filehandle 2400 without establishing state on the server. The policy of granting 2401 access or modifying files is managed by the server based on the 2402 client's state. These mechanisms can implement policy ranging from 2403 advisory only locking to full mandatory locking. 2405 8.1. Locking 2407 It is assumed that manipulating a lock is rare when compared to READ 2408 and WRITE operations. It is also assumed that crashes and network 2409 partitions are relatively rare. Therefore it is important that the 2410 READ and WRITE operations have a lightweight mechanism to indicate if 2411 they possess a held lock. A lock request contains the heavyweight 2412 information required to establish a lock and uniquely define the lock 2413 owner. 2415 The following sections describe the transition from the heavy weight 2416 information to the eventual stateid used for most client and server 2417 locking and lease interactions. 2419 Draft Specification NFS version 4 Protocol January 2000 2421 8.1.1. Client ID 2423 For each LOCK request, the client must identify itself to the server. 2424 This is done in such a way as to allow for correct lock 2425 identification and crash recovery. Client identification is 2426 accomplished with two values. 2428 o A verifier that is used to detect client reboots. 2430 o A variable length opaque array to uniquely define a client. 2432 For an operating system this may be a fully qualified host 2433 name or IP address. For a user level NFS client it may 2434 additionally contain a process id or other unique sequence. 2436 The data structure for the Client ID would then appear as: 2438 struct nfs_client_id { 2439 opaque verifier[4]; 2440 opaque id<>; 2441 } 2443 It is possible through the mis-configuration of a client or the 2444 existence of a rogue client that two clients end up using the same 2445 nfs_client_id. This situation is avoided by "negotiating" the 2446 nfs_client_id between client and server with the use of the 2447 SETCLIENTID and SETCLIENTID_CONFIRM operations. The following 2448 describes the two scenarios of negotiation. 2450 1 Client has never connected to the server 2452 In this case the client generates an nfs_client_id and 2453 unless another client has the same nfs_client_id.id field, 2454 the server accepts the request. The server also records the 2455 principal (or principal to uid mapping) from the credential 2456 in the RPC request that contains the nfs_client_id 2457 negotiation request (SETCLIENTID operation). 2459 Two clients might still use the same nfs_client_id.id due 2460 to perhaps configuration error. For example, a High 2461 Availability configuration where the nfs_client_id.id is 2462 derived from the ethernet controller address and both 2463 systems have the same address. In this case, the result is 2464 a switched union that returns in addition to 2465 NFS4ERR_CLID_INUSE, the network address (the rpcbind netid 2466 and universal address) of the client that is using the id. 2468 Draft Specification NFS version 4 Protocol January 2000 2470 2 Client is re-connecting to the server after a client reboot 2472 In this case, the client still generates an nfs_client_id 2473 but the nfs_client_id.id field will be the same as the 2474 nfs_client_id.id generated prior to reboot. If the server 2475 finds that the principal/uid is equal to the previously 2476 "registered" nfs_client_id.id, then locks associated with 2477 the old nfs_client_id are immediately released. If the 2478 principal/uid is not equal, then this is a rogue client and 2479 the request is returned in error. For more discussion of 2480 crash recovery semantics, see the section on "Crash 2481 Recovery" 2483 To mitigate retransmission of the SETCLIENTID operation, 2484 the client and server use a confirmation step. The server 2485 returns a confirmation verifier that the client then sends 2486 to the server in the SETCLIENTID_CONFIRM operation. Once 2487 the server receives the confirmation from the client, the 2488 locking state for the client is released. 2490 In both cases, upon success, NFS4_OK is returned. To help reduce the 2491 amount of data transferred on OPEN and LOCK, the server will also 2492 return a unique 64-bit clientid value that is a shorthand reference 2493 to the nfs_client_id values presented by the client. From this point 2494 forward, the client will use the clientid to refer to itself. 2496 The clientid assigned by the server should be chosen so that it will 2497 not conflict with a clientid previously assigned by the server. This 2498 applies across server restarts or reboots. When a clientid is 2499 presented to a server and that clientid is not recognized, as would 2500 happen after a server reboot, the server will reject the request with 2501 the error NFS4ERR_STALE_CLIENTID. When this happens, the client must 2502 obtain a new clientid by use of the SETCLIENTID operation and then 2503 proceed to any other necessary recovery for the server reboot case 2504 (See the section "Server Failure and Recovery"). 2506 The client must also employ the SETCLIENTID operation when it 2507 receives a NFS4ERR_STALE_STATEID error using a stateid derived from 2508 its current clientid since this also indicates a server reboot which 2509 has invalidated the existing clientid (see the next section 2510 "nfs_lockowner and stateid Definition" for details). 2512 8.1.2. Server Release of Clientid 2514 If the server determines that the client holds no associated state 2515 for its clientid and no activity from that client has been received 2516 some long period of time, the server may choose to release the 2518 Draft Specification NFS version 4 Protocol January 2000 2520 clientid. The server may make this choice for an inactive client so 2521 that resources are not consumed by those intermittently active 2522 clients. If the client contacts the server after the this release, 2523 the server must ensure the client receives the appropriate error so 2524 that it will use the SETCLIENTID/SETCLIENTID_CONFIRM sequence to 2525 establish a new identity. It should be clear that the server must be 2526 very hesitant to release a clientid since the resultant work on the 2527 client to recover from such an event will be the same burden as if 2528 the server had failed and restarted. 2530 8.1.3. nfs_lockowner and stateid Definition 2532 When requesting a lock, the client must present to the server the 2533 clientid and an identifier for the owner of the requested lock. 2534 These two fields are referred to as the nfs_lockowner and the 2535 definition of those fields are: 2537 o A clientid returned by the server as part of the client's use of 2538 the SETCLIENTID operation. 2540 o A variable length opaque array used to uniquely define the owner 2541 of a lock managed by the client. 2543 This may be a thread id, process id, or other unique value. 2545 When the server grants the lock, it responds with a unique 64-bit 2546 stateid. The stateid is used as a shorthand reference to the 2547 nfs_lockowner, since the server will be maintaining the 2548 correspondence between them. 2550 The server is free to form the stateid in any manner that it chooses 2551 as long as it is able to recognize invalid and out-of-date stateids. 2552 This requirement includes those stateids generated by earlier 2553 instances of the server. From this, the client can be properly 2554 notified of a server restart. This notification will occur when the 2555 client presents a stateid to the server from a previous 2556 instantiation. 2558 The server must be able to distinguish the following situations and 2559 return the error as specified: 2561 o The stateid was generated by an earlier server instance (i.e. 2562 before a server reboot). The error NFS4ERR_STALE_STATEID should 2563 be returned. 2565 o The stateid was generated by the current server instance but the 2567 Draft Specification NFS version 4 Protocol January 2000 2569 stateid no longer designates the current locking state for the 2570 lockowner-file pair in question (i.e. one or more locking 2571 operations has occurred). The error NFS4ERR_OLD_STATEID should 2572 be returned. 2574 This error condition will only occur when the client issues a 2575 locking request which changes a stateid while an I/O request 2576 that uses that stateid is outstanding. 2578 o The stateid was generated by the current server instance but the 2579 stateid does not designate a locking state for any active 2580 lockowner-file pair. The error NFS4ERR_BAD_STATEID should be 2581 returned. 2583 This error condition will occur when there has been a logic 2584 error on the part of the client or server. This should not 2585 happen. 2587 One mechanism that may be used to satisfy these requirements is for 2588 the server to divide stateids into three fields: 2590 o A server verifier which uniquely designates a particular server 2591 instantiation. 2593 o An index into a table of locking-state structures. 2595 o A sequence value which is incremented for each stateid that is 2596 associated with the same index into the locking-state table. 2598 By matching the incoming stateid and its field values with the state 2599 held at the server, the server is able to easily determine if a 2600 stateid is valid for its current instantiation and state. If the 2601 stateid is not valid, the appropriate error can be supplied to the 2602 client. 2604 8.1.4. Use of the stateid 2606 All READ and WRITE operations contain a stateid. If the 2607 nfs_lockowner performs a READ or WRITE on a range of bytes within a 2608 locked range, the stateid (previously returned by the server) must be 2609 used to indicate that appropriate lock (record or share) is held. If 2610 no state is established by the client, either record lock or share 2611 lock, a stateid of all bits 0 is used. If no conflicting locks are 2612 held on the file, the server may service the READ or WRITE operation. 2613 If a conflict with an explicit lock occurs, an error is returned for 2614 the operation (NFS4ERR_LOCKED). This allows "mandatory locking" to be 2616 Draft Specification NFS version 4 Protocol January 2000 2618 implemented. 2620 A stateid of all bits 1 (one) allows READ operations to bypass record 2621 locking checks at the server. However, WRITE operations with stateid 2622 with bits all 1 (one) do not bypass record locking checks. File 2623 locking checks are handled by the OPEN operation (see the section 2624 "OPEN/CLOSE Operations"). 2626 An explicit lock may not be granted while a READ or WRITE operation 2627 with conflicting implicit locking is being performed. 2629 8.1.5. Sequencing of Lock Requests 2631 Locking is different than most NFS operations as it requires "at- 2632 most-one" semantics that are not provided by ONCRPC. In the face of 2633 retransmission or reordering, lock or unlock requests must have a 2634 well defined and consistent behavior. To accomplish this, each lock 2635 request contains a sequence number that is a consecutively increasing 2636 integer. Different nfs_lockowners have different sequences. The 2637 server maintains the last sequence number (L) received and the 2638 response that was returned. 2640 If a request with a previous sequence number (r < L) is received, it 2641 is rejected with the return of error NFS4ERR_BAD_SEQID. Given a 2642 properly-functioning client, the response to (r) must have been 2643 received before the last request (L) was sent. If a duplicate of 2644 last request (r == L) is received, the stored response is returned. 2645 If a request beyond the next sequence (r == L + 2) is received, it is 2646 rejected with the return of error NFS4ERR_BAD_SEQID. Sequence 2647 history is reinitialized whenever the client verifier changes. 2649 Since the sequence number is represented with an unsigned 32-bit 2650 integer, the arithmetic involved with the sequence number is mod 2651 2^32. 2653 It is critical the server maintain the last response sent to the 2654 client to provide a more reliable cache of duplicate non-idempotent 2655 requests than that of the traditional cache described in [Juszczak]. 2656 The traditional duplicate request cache uses a least recently used 2657 algorithm for removing unneeded requests. However, the last lock 2658 request and response on a given nfs_lockowner must be cached as long 2659 as the lock state exists on the server. 2661 8.1.6. Recovery from Replayed Requests 2663 As described above, the sequence number is per nfs_lockowner. As 2665 Draft Specification NFS version 4 Protocol January 2000 2667 long as the server maintains the last sequence number received and 2668 follows the methods described above, there are no risks of a 2669 byzantine router re-sending old requests. The server need only 2670 maintain the nfs_lockowner, sequence number state as long as there 2671 are open files or closed files with locks outstanding. 2673 LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence 2674 number and therefore the risk of the replay of these operations 2675 resulting in undesired effects is non-existent while the server 2676 maintains the nfs_lockowner state. 2678 8.1.7. Releasing nfs_lockowner State 2680 When a particular nfs_lockowner no longer holds open or file locking 2681 state at the server, the server may choose to release the sequence 2682 number state associated with the nfs_lockowner. The server may make 2683 this choice based on lease expiration, for the reclamation of server 2684 memory, or other implementation specific details. In any event, the 2685 server is able to do this safely only when the nfs_lockowner no 2686 longer is being utilized by the client. The server may choose to 2687 hold the nfs_lockowner state in the event that retransmitted requests 2688 are received. However, the period to hold this state is 2689 implementation specific. 2691 In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is 2692 retransmitted after the server has previously released the 2693 nfs_lockowner state, the server will find that the nfs_lockowner has 2694 no files open and an error will be returned to the client. If the 2695 nfs_lockowner does have a file open, the stateid will not match and 2696 again an error is returned to the client. 2698 In the case that an OPEN is retransmitted and the nfs_lockowner is 2699 being used for the first time or the nfs_lockowner state has been 2700 previously released by the server, the use of the OPEN_CONFIRM 2701 operation will prevent incorrect behavior. When the server observes 2702 the use of the nfs_lockowner for the first time, it will direct the 2703 client to perform the OPEN_CONFIRM for the corresponding OPEN. This 2704 sequence establishes the use of an nfs_lockowner and associated 2705 sequence number. See the section "OPEN_CONFIRM - Confirm Open" for 2706 further details. 2708 8.2. Lock Ranges 2710 The protocol allows a lock owner to request a lock with one byte 2711 range and then either upgrade or unlock a sub-range of the initial 2712 lock. It is expected that this will be an uncommon type of request. 2714 Draft Specification NFS version 4 Protocol January 2000 2716 In any case, servers or server file systems may not be able to 2717 support sub-range lock semantics. In the event that a server 2718 receives a locking request that represents a sub-range of current 2719 locking state for the lock owner, the server is allowed to return the 2720 error NFS4ERR_LOCK_RANGE to signify that it does not support sub- 2721 range lock operations. Therefore, the client should be prepared to 2722 receive this error and, if appropriate, report the error to the 2723 requesting application. 2725 The client is discouraged from coalescing adjacent ranges since the 2726 server may not support sub-range requests and for reasons related to 2727 the recovery of file locking state in the event of server failure. 2728 As discussed in the section "Server Failure and Recovery" below, the 2729 server may employ certain optimizations during recovery that work 2730 effectively only when the client's behavior during lock recovery is 2731 similar to the client's locking behavior prior to server failure. 2733 8.3. Blocking Locks 2735 Some clients require the support of blocking locks. The NFS version 2736 4 protocol must not rely on a callback mechanism and therefore is 2737 unable to notify a client when a previously denied lock has been 2738 granted. Clients have no choice but to continually poll for the 2739 lock. This presents a fairness problem. Two new lock types are 2740 added, READW and WRITEW, and are used to indicate to the server that 2741 the client is requesting a blocking lock. The server should maintain 2742 an ordered list of pending blocking locks. When the conflicting lock 2743 is released, the server may wait the lease period for the first 2744 waiting client to re-request the lock. After the lease period 2745 expires the next waiting client request is allowed the lock. Clients 2746 are required to poll at an interval sufficiently small that it is 2747 likely to acquire the lock in a timely manner. The server is not 2748 required to maintain a list of pending blocked locks as it is used to 2749 increase fairness and not correct operation. Because of the 2750 unordered nature of crash recovery, storing of lock state to stable 2751 storage would be required to guarantee ordered granting of blocking 2752 locks. 2754 Servers may also note the lock types and delay returning denial of 2755 the request to allow extra time for a conflicting lock to be 2756 released, allowing a successful return. In this way, clients can be 2757 avoid the burden of needlessly frequent polling for blocking locks. 2758 The server should take care in the length of delay in the event the 2759 client retransmits the request. 2761 Draft Specification NFS version 4 Protocol January 2000 2763 8.4. Lease Renewal 2765 The purpose of a lease is to allow a server to remove stale locks 2766 that are held by a client that has crashed or is otherwise 2767 unreachable. It is not a mechanism for cache consistency and lease 2768 renewals may not be denied if the lease interval has not expired. 2770 The following events cause implicit renewal of all of the leases for 2771 a given client (i.e. all those sharing a given clientid). Each of 2772 these is a positive indication that the client is still active and 2773 that the associated state held at the server, for the client, is 2774 still valid. 2776 o An OPEN with a valid clientid. 2778 o Any operation made with a valid stateid (CLOSE, DELEGRETURN, 2779 LOCK, LOCKU, OPEN, OPEN_CONFIRM, READ, RENEW, SETATTR, WRITE). 2780 This does not include the special stateids of all bits 0 or all 2781 bits 1. 2783 Note that if the client had restarted or rebooted, the 2784 client would not be making these requests without issuing 2785 the SETCLIENTID operation. The use of the SETCLIENTID 2786 operation (possibly with the addition of the optional 2787 SETCLIENTID_CONFIRM operation) notifies the server to drop 2788 the locking state associated with the client. 2790 If the server has rebooted, the stateids 2791 (NFS4ERR_STALE_STATEID error) or the clientid 2792 (NFS4ERR_STALE_CLIENTID error) will not be valid hence 2793 preventing spurious renewals. 2795 This approach allows for low overhead lease renewal which scales 2796 well. In the typical case no extra RPC calls are required for lease 2797 renewal and in the worst case one RPC is required every lease period 2798 (i.e. a RENEW operation). The number of locks held by the client is 2799 not a factor since all state for the client is involved with the 2800 lease renewal action. 2802 Since all operations that create a new lease also renew existing 2803 leases, the server must maintain a common lease expiration time for 2804 all valid leases for a given client. This lease time can then be 2805 easily updated upon implicit lease renewal actions. 2807 8.5. Crash Recovery 2809 The important requirement in crash recovery is that both the client 2811 Draft Specification NFS version 4 Protocol January 2000 2813 and the server know when the other has failed. Additionally, it is 2814 required that a client sees a consistent view of data across server 2815 restarts or reboots. All READ and WRITE operations that may have 2816 been queued within the client or network buffers must wait until the 2817 client has successfully recovered the locks protecting the READ and 2818 WRITE operations. 2820 8.5.1. Client Failure and Recovery 2822 In the event that a client fails, the server may recover the client's 2823 locks when the associated leases have expired. Conflicting locks 2824 from another client may only be granted after this lease expiration. 2825 If the client is able to restart or reinitialize within the lease 2826 period the client may be forced to wait the remainder of the lease 2827 period before obtaining new locks. 2829 To minimize client delay upon restart, lock requests are associated 2830 with an instance of the client by a client supplied verifier. This 2831 verifier is part of the initial SETCLIENTID call made by the client. 2832 The server returns a clientid as a result of the SETCLIENTID 2833 operation. The client then confirms the use of the verifier with 2834 SETCLIENTID_CONFIRM. The clientid in combination with an opaque 2835 owner field is then used by the client to identify the lock owner for 2836 OPEN. This chain of associations is then used to identify all locks 2837 for a particular client. 2839 Since the verifier will be changed by the client upon each 2840 initialization, the server can compare a new verifier to the verifier 2841 associated with currently held locks and determine that they do not 2842 match. This signifies the client's new instantiation and subsequent 2843 loss of locking state. As a result, the server is free to release 2844 all locks held which are associated with the old clientid which was 2845 derived from the old verifier. 2847 For secure environments, a change in the verifier must only cause the 2848 release of locks associated with the authenticated requester. This 2849 is required to prevent a rogue entity from freeing otherwise valid 2850 locks. 2852 Note that the verifier must have the same uniqueness properties of 2853 the verifier for the COMMIT operation. 2855 8.5.2. Server Failure and Recovery 2857 If the server loses locking state (usually as a result of a restart 2858 or reboot), it must allow clients time to discover this fact and re- 2860 Draft Specification NFS version 4 Protocol January 2000 2862 establish the lost locking state. The client must be able to re- 2863 establish the locking state without having the server deny valid 2864 requests because the server has granted conflicting access to another 2865 client. Likewise, if there is the possibility that clients have not 2866 yet re-established their locking state for a file, the server must 2867 disallow READ and WRITE operations for that file. The duration of 2868 this recovery period is equal to the duration of the lease period. 2870 A client can determine that server failure (and thus loss of locking 2871 state) has occurred, when it receives one of two errors. The 2872 NFS4ERR_STALE_STATEID error indicates a stateid invalidated by a 2873 reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a 2874 clientid invalidated by reboot or restart. When either of these are 2875 received, the client must establish a new clientid (See the section 2876 "Client ID") and re-establish the locking state as discussed below. 2878 The period of special handling of locking and READs and WRITEs, equal 2879 in duration to the lease period, is referred to as the "grace 2880 period". During the grace period, clients recover locks and the 2881 associated state by reclaim-type locking requests (i.e. LOCK requests 2882 with reclaim set to true and OPEN operations with a claim type of 2883 CLAIM_PREVIOUS). During the grace period, the server must reject 2884 READ and WRITE operations and non-reclaim locking requests (i.e. 2885 other LOCK and OPEN operations) with an error of NFS4ERR_GRACE. 2887 If the server can reliably determine that granting a non-reclaim 2888 request will not conflict with reclamation of locks by other clients, 2889 the NFS4ERR_GRACE error does not have to be returned and the non- 2890 reclaim client request can be serviced. For the server to be able to 2891 service READ and WRITE operations during the grace period, it must 2892 again be able to guarantee that no possible conflict could arise 2893 between an impending reclaim locking request and the READ or WRITE 2894 operation. If the server is unable to offer that guarantee, the 2895 NFS4ERR_GRACE error must be returned to the client. 2897 For a server to provide simple, valid handling during the grace 2898 period, the easiest method is to simply reject all non-reclaim 2899 locking requests and READ and WRITE operations by returning the 2900 NFS4ERR_GRACE error. However, a server may keep information about 2901 granted locks in stable storage. With this information, the server 2902 could determine if a regular lock or READ or WRITE operation can be 2903 safely processed. 2905 For example, if a count of locks on a given file is available in 2906 stable storage, the server can track reclaimed locks for the file and 2907 when all reclaims have been processed, non-reclaim locking requests 2908 may be processed. This way the server can ensure that non-reclaim 2909 locking requests will not conflict with potential reclaim requests. 2911 Draft Specification NFS version 4 Protocol January 2000 2913 With respect to I/O requests, if the server is able to determine that 2914 there are no outstanding reclaim requests for a file by information 2915 from stable storage or another similar mechanism, the processing of 2916 I/O requests could proceed normally for the file. 2918 To reiterate, for a server that allows non-reclaim lock and I/O 2919 requests to be processed during the grace period, it MUST determine 2920 that no lock subsequently reclaimed will be rejected and that no lock 2921 subsequently reclaimed would have prevented any I/O operation 2922 processed during the grace period. 2924 Clients should be prepared for the return of NFS4ERR_GRACE errors for 2925 non-reclaim lock and I/O requests. In this case the client should 2926 employ a backoff and retry mechanism for the request. Timeout 2927 periods should be chosen to avoid overwhelming a server. The client 2928 must account for the server that is able to perform I/O and non- 2929 reclaim locking requests within the grace period as well as those 2930 that can not do so. 2932 A reclaim-type locking request outside the server's grace period can 2933 only succeed if the server can guarantee that no conflicting lock or 2934 I/O request has been granted since reboot or restart. 2936 8.5.3. Network Partitions and Recovery 2938 If the duration of a network partition is greater than the lease 2939 period provided by the server, the server will have not received a 2940 lease renewal from the client. If this occurs, the server may free 2941 all locks held for the client. As a result, all stateids held by the 2942 client will become invalid or stale. Once the client is able to 2943 reach the server after such a network partition, all I/O submitted by 2944 the client with the now invalid stateids will fail with the server 2945 returning the error NFS4ERR_EXPIRED. Once this error is received, 2946 the client will suitably notify the application that held the lock. 2948 As a courtesy to the client or as an optimization, the server may 2949 continue to hold locks on behalf of a client for which recent 2950 communication has extended beyond the lease period. If the server 2951 receives a lock or I/O request that conflicts with one of these 2952 courtesy locks, the server must free the courtesy lock and grant the 2953 new request. 2955 In the event of a network partition with a duration extending beyond 2956 the expiration of a client's leases, the server MUST employ a method 2957 of recording this fact in its stable storage. Conflicting locks 2958 requests from another client may be serviced after the lease 2959 expiration. There are various scenarios involving server failure 2961 Draft Specification NFS version 4 Protocol January 2000 2963 after such an event that require the storage of these lease 2964 expirations or network partitions. One scenario is as follows: 2966 A client holds a lock at the server and encounters a 2967 network partition and is unable to renew the associated 2968 lease. A second client obtains a conflicting lock and then 2969 frees the lock. After the unlock request by the second 2970 client, the server reboots or reinitializes. Once the 2971 server recovers, the network partition heals and the 2972 original client attempts to reclaim the original lock. 2974 In this scenario and without any state information, the server will 2975 allow the reclaim and the client will be in an inconsistent state 2976 because the server or the client has no knowledge of the conflicting 2977 lock. 2979 The server may choose to store this lease expiration or network 2980 partitioning state in a way that will only identify the client as a 2981 whole. Note that this may potentially lead to lock reclaims being 2982 denied unnecessarily because of a mix of conflicting and non- 2983 conflicting locks. The server may also choose to store information 2984 about each lock that has an expired lease with an associated 2985 conflicting lock. The choice of the amount and type of state 2986 information that is stored is left to the implementor. In any case, 2987 the server must have enough state information to enable correct 2988 recovery from multiple partitions and multiple server failures. 2990 8.6. Recovery from a Lock Request Timeout or Abort 2992 In the event a lock request times out, a client may decide to not 2993 retry the request. The client may also abort the request when the 2994 process for which it was issued is terminated (e.g. in UNIX due to a 2995 signal. It is possible though that the server received the request 2996 and acted upon it. This would change the state on the server without 2997 the client being aware of the change. It is paramount that the 2998 client re-synchronize state with server before it attempts any other 2999 operation that takes a seqid and/or a stateid with the same 3000 nfs_lockowner. This is straightforward to do without a special re- 3001 synchronize operation. 3003 Since the server maintains the last lock request and response 3004 received on the nfs_lockowner, for each nfs_lockowner, the client 3005 should cache the last lock request it sent such that the lock request 3006 did not receive a response. From this, the next time the client does 3007 a lock operation for the nfs_lockowner, it can send the cached 3008 request, if there is one, and if the request was one that established 3010 Draft Specification NFS version 4 Protocol January 2000 3012 state (e.g. a LOCK or OPEN operation) the client can follow up with a 3013 request to remove the state (e.g. a LOCKU or CLOSE operation). With 3014 this approach, the sequencing and stateid information on the client 3015 and server for the given nfs_lockowner will re-synchronize and in 3016 turn the lock state will re-synchronize. 3018 8.7. Server Revocation of Locks 3020 At any point, the server can revoke locks held by a client and the 3021 client must be prepared for this event. When the client detects that 3022 its locks have been or may have been revoked, the client is 3023 responsible for validating the state information between itself and 3024 the server. Validating locking state for the client means that it 3025 must verify or reclaim state for each lock currently held. 3027 The first instance of lock revocation is upon server reboot or re- 3028 initialization. In this instance the client will receive an error 3029 (NFS4ERR_STALE_STATEID or NFS4ERR_STALE_CLIENTID) and the client will 3030 proceed with normal crash recovery as described in the previous 3031 section. 3033 The second lock revocation event can occur as a result of 3034 administrative intervention within the lease period. While this is 3035 considered a rare event, it is possible that the server's 3036 administrator has decided to release or revoke a particular lock held 3037 by the client. As a result of revocation, the client will receive an 3038 error of NFS4ERR_EXPIRED and the error is received within the lease 3039 period for the lock. In this instance the client may assume that 3040 only the nfs_lockowner's locks have been lost. The client notifies 3041 the lock holder appropriately. The client may not assume the lease 3042 period has been renewed as a result of failed operation. 3044 The third lock revocation event is the inability to renew the lease 3045 period. While this is considered a rare or unusual event, the client 3046 must be prepared to recover. Both the server and client will be able 3047 to detect the failure to renew the lease and are capable of 3048 recovering without data corruption. For the server, it tracks the 3049 last renewal event serviced for the client and knows when the lease 3050 will expire. Similarly, the client must track operations which will 3051 renew the lease period. Using the time that each such request was 3052 sent and the time that the corresponding reply was received, the 3053 client should bound the time that the corresponding renewal could 3054 have occurred on the server and thus determine if it is possible that 3055 a lease period expiration could have occurred. 3057 When the client determines the lease period may have expired, the 3058 client must mark all locks held for the associated lease as 3060 Draft Specification NFS version 4 Protocol January 2000 3062 "unvalidated". This means the client has been unable to re-establish 3063 or confirm the appropriate lock state with the server. As described 3064 in the previous section on crash recovery, there are scenarios in 3065 which the server may grant conflicting locks after the lease period 3066 has expired for a client. When it is possible that the lease period 3067 has expired, the client must validate each lock currently held to 3068 ensure that a conflicting lock has not been granted. The client may 3069 accomplish this task by issuing an I/O request, either a pending I/O 3070 or a zero-length read, specifying the stateid associated with the 3071 lock in question. If the response to the request is success, the 3072 client has validated all of the locks governed by that stateid and 3073 re-established the appropriate state between itself and the server. 3074 If the I/O request is not successful, then one or more of the locks 3075 associated with the stateid was revoked by the server and the client 3076 must notify the owner. 3078 8.8. Share Reservations 3080 A share reservation is a mechanism to control access to a file. It 3081 is a separate and independent mechanism from record locking. When a 3082 client opens a file, it issues an OPEN operation to the server 3083 specifying the type of access required (READ, WRITE, or BOTH) and the 3084 type of access to deny others (deny NONE, READ, WRITE, or BOTH). If 3085 the OPEN fails the client will fail the application's open request. 3087 Pseudo-code definition of the semantics: 3089 if ((request.access & file_state.deny)) || 3090 (request.deny & file_state.access)) 3091 return (NFS4ERR_DENIED) 3093 The constants used for the OPEN and OPEN_DOWNGRADE operations for the 3094 access and deny fields are as follows: 3096 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 3097 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 3098 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 3100 const OPEN4_SHARE_DENY_NONE = 0x00000000; 3101 const OPEN4_SHARE_DENY_READ = 0x00000001; 3102 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 3103 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 3105 Draft Specification NFS version 4 Protocol January 2000 3107 8.9. OPEN/CLOSE Operations 3109 To provide correct share semantics, a client MUST use the OPEN 3110 operation to obtain the initial filehandle and indicate the desired 3111 access and what if any access to deny. Even if the client intends to 3112 use a stateid of all 0's or all 1's, it must still obtain the 3113 filehandle for the regular file with the OPEN operation so the 3114 appropriate share semantics can be applied. For clients that do not 3115 have a deny mode built into their open programming interfaces, deny 3116 equal to NONE should be used. 3118 The OPEN operation with the CREATE flag, also subsumes the CREATE 3119 operation for regular files as used in previous versions of the NFS 3120 protocol. This allows a create with a share to be done atomically. 3122 The CLOSE operation removes all share locks held by the nfs_lockowner 3123 on that file. If record locks are held, the client SHOULD release 3124 all locks before issuing a CLOSE. The server MAY free all 3125 outstanding locks on CLOSE but some servers may not support the CLOSE 3126 of a file that still has record locks held. The server MUST return 3127 failure if any locks would exist after the CLOSE. 3129 The LOOKUP operation is preserved and will return a filehandle 3130 without establishing any lock state on the server. Without a valid 3131 stateid, the server will assume the client has the least access. For 3132 example, a file opened with deny READ/WRITE cannot be accessed using 3133 a filehandle obtained through LOOKUP because it would not have a 3134 valid stateid (i.e. using a stateid of all bits 0 or all bits 1). 3136 8.10. Open Upgrade and Downgrade 3138 When an OPEN is done for a file and the lockowner for which the open 3139 is being done already has the file open, the result is to upgrade the 3140 open file status maintained on the server to include the access and 3141 deny bits specified by the new OPEN as well as those for the existing 3142 OPEN. The result is that there is one open file, as far as the 3143 protocol is concerned, and it includes the union of the access and 3144 deny bits for all of the OPEN requests completed. Only a single 3145 CLOSE will be done to reset the effects of both OPEN's. Note that 3146 the client, when issuing the OPEN, may not know that the same file is 3147 in fact being opened. The above only applies if both OPEN's result 3148 in the OPEN'ed object being designated by the same filehandle. 3150 When the server chooses to export multiple filehandles corresponding 3151 to the same file object and returns different filehandles on two 3152 different OPEN's of the same file object, the server MUST NOT "OR" 3153 together the access and deny bits and coalesce the two open files. 3155 Draft Specification NFS version 4 Protocol January 2000 3157 Instead the server must maintain separate OPEN's with separate 3158 stateid's and will require separate CLOSE's to free them. 3160 When multiple open files on the client are merged into a single open 3161 file object on the server, the close of one of the open files (on the 3162 client) may necessitate change of the access and deny status of the 3163 open file on the server. This is because the union of the access and 3164 deny bits for the remaining open's may be smaller (i.e. a proper 3165 subset) than previously. The OPEN_DOWNGRADE operation is used to 3166 make the necessary change and the client should use it to update the 3167 server so that share reservation requests by other clients are 3168 handled properly. 3170 8.11. Short and Long Leases 3172 When determining the time period for the server lease, the usual 3173 lease tradeoffs apply. Short leases are good for fast server 3174 recovery at a cost of increased RENEW or READ (with zero length) 3175 requests. Longer leases are certainly kinder and gentler to large 3176 internet servers trying to handle a very large numbers of clients. 3177 The number of RENEW requests drop in proportion to the lease time. 3178 The disadvantages of long leases are slower recovery after server 3179 failure (server must wait for leases to expire and grace period 3180 before granting new lock requests) and increased file contention (if 3181 client fails to transmit an unlock request then server must wait for 3182 lease expiration before granting new locks). 3184 Long leases are usable if the server is able to store lease state in 3185 non-volatile memory. Upon recovery, the server can reconstruct the 3186 lease state from its non-volatile memory and continue operation with 3187 its clients and therefore long leases are not an issue. 3189 8.12. Clocks and Calculating Lease Expiration 3191 To avoid the need for synchronized clocks, lease times are granted by 3192 the server as a time delta. However, there is a requirement that the 3193 client and server clocks do not drift excessively over the duration 3194 of the lock. There is also the issue of propagation delay across the 3195 network which could easily be several hundred milliseconds as well as 3196 the possibility that requests will be lost and need to be 3197 retransmitted. 3199 To take propagation delay into account, the client should subtract it 3200 from lease times (e.g. if the client estimates the one-way 3201 propagation delay as 200 msec, then it can assume that the lease is 3202 already 200 msec old when it gets it). In addition, it will take 3204 Draft Specification NFS version 4 Protocol January 2000 3206 another 200 msec to get a response back to the server. So the client 3207 must send a lock renewal or write data back to the server 400 msec 3208 before the lease would expire. 3210 Draft Specification NFS version 4 Protocol January 2000 3212 9. Client-Side Caching 3214 Client-side caching of data, of file attributes, and of file names is 3215 essential to providing good performance with the NFS protocol. 3216 Providing distributed cache coherence is a difficult problem and 3217 previous versions of the NFS protocol have not attempted it. 3218 Instead, several NFS client implementation techniques have been used 3219 to reduce the problems that a lack of coherence poses for users. 3220 These techniques have not been clearly defined by earlier protocol 3221 specifications and it is often unclear what is valid or invalid 3222 client behavior. 3224 The NFS version 4 protocol uses many techniques similar to those that 3225 have been used in previous protocol versions. The NFS version 4 3226 protocol does not provide distributed cache coherence. However, it 3227 defines a more limited set of caching guarantees to allow locks and 3228 share reservations to be used without destructive interference from 3229 client side caching. 3231 In addition, the NFS version 4 protocol introduces a delegation 3232 mechanism which allows many decisions normally made by the server to 3233 be made locally by clients. This mechanism provides efficient 3234 support of the common cases where sharing is infrequent or where 3235 sharing is read-only. 3237 9.1. Performance Challenges for Client-Side Caching 3239 Caching techniques used in previous versions of the NFS protocol have 3240 been successful in providing good performance. However, several 3241 scalability challenges can arise when those techniques are used with 3242 very large numbers of clients. This is particularly true when 3243 clients are geographically distributed which classically increases 3244 the latency for cache revalidation requests. 3246 The previous versions of the NFS protocol repeat their file data 3247 cache validation requests at the time the file is opened. This 3248 behavior can have serious performance drawbacks. A common case is 3249 one in which a file is only accessed by a single client. Therefore, 3250 sharing is infrequent. 3252 In this case, repeated reference to the server to find that no 3253 conflicts exist is expensive. A better option with regards to 3254 performance is to allow a client that repeatedly opens a file to do 3255 so without reference to the server. This is done until potentially 3256 conflicting operations from another client actually occur. 3258 A similar situation arises in connection with file locking. Sending 3260 Draft Specification NFS version 4 Protocol January 2000 3262 file lock and unlock requests to the server as well as the read and 3263 write requests necessary to make data caching consistent with the 3264 locking semantics (see the section "Data Caching and File Locking") 3265 can severely limit performance. When locking is used to provide 3266 protection against infrequent conflicts, a large penalty is incurred. 3267 This penalty may discourage the use of file locking by applications. 3269 The NFS version 4 protocol provides more aggressive caching 3270 strategies with the following design goals: 3272 o Compatibility with a large range of server semantics. 3274 o Provide the same caching benefits as previous versions of the 3275 NFS protocol when unable to provide the more aggressive model. 3277 o Requirements for aggressive caching are organized so that a 3278 large portion of the benefit can be obtained even when not all 3279 of the requirements can be met. 3281 The appropriate requirements for the server are discussed in later 3282 sections in which specific forms of caching are covered. (see the 3283 section "Open Delegation"). 3285 9.2. Delegation and Callbacks 3287 Recallable delegation of server responsibilities for a file to a 3288 client improves performance by avoiding repeated requests to the 3289 server in the absence of inter-client conflict. With the use of a 3290 "callback" RPC from server to client, a server recalls delegated 3291 responsibilities when another client engages in sharing of a 3292 delegated file. 3294 A delegation is passed from the server to the client, specifying the 3295 object of the delegation and the type of delegation. There are 3296 different types of delegations but each type contains a stateid to be 3297 used to represent the delegation when performing operations that 3298 depend on the delegation. This stateid is similar to those 3299 associated with locks and share reservations but differs in that the 3300 stateid for a delegation is associated with a clientid and may be 3301 used on behalf of all the nfs_lockowners for the given client. A 3302 delegation is made to the client as a whole and not to any specific 3303 process or thread of control within it. 3305 Because callback RPCs may not work in all environments (due to 3306 firewalls, for example), correct protocol operation does not depend 3307 on them. Preliminary testing of callback functionality by means of a 3309 Draft Specification NFS version 4 Protocol January 2000 3311 CB_NULL procedure determines whether callbacks can be supported. The 3312 CB_NULL procedure checks the continuity of the callback path. A 3313 server makes a preliminary assessment of callback availability to a 3314 given client and avoids delegating responsibilities until it has 3315 determined that callbacks are supported. Because the granting of a 3316 delegation is always conditional upon the absence of conflicting 3317 access, clients must not assume that a delegation will be granted and 3318 they must always be prepared for OPENs to be processed without any 3319 delegations being granted. 3321 Once granted, a delegation behaves in most ways like a lock. There 3322 is an associated lease that is subject to renewal together with all 3323 of the other leases held by that client. 3325 Unlike locks, an operation by a second client to a delegated file 3326 will cause the server to recall a delegation through a callback. 3328 On recall, the client holding the delegation must flush modified 3329 state (such as modified data) to the server and return the 3330 delegation. The conflicting request will not receive a response 3331 until the recall is complete. The recall is considered complete when 3332 the client returns the delegation or the server times out on the 3333 recall and revokes the delegation as a result of the timeout. 3334 Following the resolution of the recall, the server has the 3335 information necessary to grant or deny the second client's request. 3337 At the time the client receives a delegation recall, it may have 3338 substantial state that needs to be flushed to the server. Therefore, 3339 the server should allow sufficient time for the recall RPC to 3340 complete since it may involve numerous RPCs to the server. If the 3341 server is able to determine that the client is diligently flushing 3342 state to the server as a result of the recall, the server may extend 3343 the usual time allowed for a recall. However, the time allowed for 3344 recall completion should not be unbounded. 3346 An example of this is when responsibility to mediate opens on a given 3347 file is delegated to a client (see the section "Open Delegation"). 3348 The server will not know what opens are in effect on the client. 3349 Without this knowledge the server will be unable to determine if the 3350 access and deny state for the file allows any particular open until 3351 the delegation for the file has been returned. 3353 A client failure or a network partition can result in failure to 3354 respond to a recall callback. In this case, the server will revoke 3355 the delegation which in turn will render useless any modified state 3356 still on the client. 3358 Draft Specification NFS version 4 Protocol January 2000 3360 9.2.1. Delegation Recovery 3362 There are three situations that delegation recovery must deal with: 3364 o Client reboot or restart 3366 o Server reboot or restart 3368 o Network partition (full or callback-only) 3370 In the event the client reboots or restarts, the failure to renew 3371 leases will result in the revocation of record locks and share 3372 reservations. Delegations, however, may treated a bit differently. 3374 There will be situations in which delegations will need to be 3375 reestablished after a client reboots or restarts. The reason for 3376 this is the client may have file data stored locally and this data 3377 was associated with the previously held delegations. The client will 3378 need to reestablish the appropriate file state on the server. 3380 To allow for this type of client recovery, the server may extend the 3381 period for delegation recovery beyond the typical lease expiration 3382 period. This implies that requests from other clients that conflict 3383 with these delegations will need to wait. This behavior is 3384 consistent with the normal recall process may take significant time 3385 because of the client's need to flush state to the server. This 3386 longer interval would increase the window for clients to reboot and 3387 consult stable storage so that the delegations can be reclaimed. For 3388 open delegations, such delegations are reclaimed using OPEN with a 3389 claim type of CLAIM_DELEGATE_PREV. (see the sections on "Data 3390 Caching and Revocation" and "Operation 18: OPEN" for discussion of 3391 open delegation and the details of OPEN respectively). 3393 When the server reboots or restarts, delegations are reclaimed (using 3394 the OPEN operation with CLAIM_DELEGATE_PREV) in a similar fashion to 3395 record locks and share reservations. However, there is a slight 3396 semantic difference. In the normal case if the server decides that a 3397 delegation should not be granted, it performs the requested action 3398 (e.g. OPEN) without granting any delegation. For reclaim, the server 3399 grants the delegation but a special designation is applied so that 3400 the client treats the delegation as having been granted but recalled 3401 by the server. Because of this, the client has the duty to write all 3402 modified state to the server and then return the delegation. This 3403 process of handling delegation reclaim reconciles three principles of 3404 the NFS Version 4 protocol: 3406 Draft Specification NFS version 4 Protocol January 2000 3408 o Upon reclaim, a client reporting resources assigned to it by an 3409 earlier server instance must be granted those resources. 3411 o The server has unquestionable authority to determine whether 3412 delegations are to be granted and, once granted, whether they 3413 are to be continued. 3415 o The use of callbacks is not to be depended upon until the client 3416 has proven its ability to receive them. 3418 When a network partition occurs, delegations are subject to freeing 3419 by the server when the lease renewal period expires. This is similar 3420 to the behavior for locks and share reservations. For delegations, 3421 however, the server may extend the period in which conflicting 3422 requests are held off. Eventually the occurrence of a conflicting 3423 request from another client will cause revocation of the delegation. 3424 A loss of the callback path (e.g. by later network configuration 3425 change) will have the same effect. A recall request will fail and 3426 revocation of the delegation will result. 3428 A client normally finds out about revocation of a delegation when it 3429 uses a stateid associated with a delegation and receives the error 3430 NFS4ERR_EXPIRED. It also may find out about delegation revocation 3431 after a client reboot when it attempts to reclaim a delegation and 3432 receives that same error. Note that in the case of a revoked write 3433 open delegation, there are issues because data may have been modified 3434 by the client whose delegation is revoked and separately by other 3435 clients. See the section "Revocation Recovery for Write Open 3436 Delegation" for a discussion of such issues. Note also that when 3437 delegations are revoked, information about the revoked delegation 3438 will be written by the server to stable storage (as described in the 3439 section "Crash Recovery"). This is done to deal with the case in 3440 which a server reboots after revoking a delegation but before the 3441 client holding the revoked delegation is notified about the 3442 revocation. 3444 9.3. Data Caching 3446 When applications share access to a set of files, they need to be 3447 implemented so as to take account of the possibility of conflicting 3448 access by another application. This is true whether the applications 3449 in question execute on different clients or reside on the same 3450 client. 3452 Share reservations and record locks are the facilities the NFS 3453 version 4 protocol provides to allow applications to coordinate 3454 access by providing mutual exclusion facilities. The NFS version 4 3456 Draft Specification NFS version 4 Protocol January 2000 3458 protocol's data caching must be implemented such that it does not 3459 invalidate the assumptions that those using these facilities depend 3460 upon. 3462 9.3.1. Data Caching and OPENs 3464 In order to avoid invalidating the sharing assumptions that 3465 applications rely on, NFS version 4 clients should not provide cached 3466 data to applications or modify it on behalf of an application when it 3467 would not be valid to obtain or modify that same data via a READ or 3468 WRITE operation. 3470 Furthermore, in the absence of open delegation (see the section "Open 3471 Delegation") two additional rules apply. Note that these rules are 3472 obeyed in practice by many NFS version 2 and version 3 clients. 3474 o First, cached data present on a client must be revalidated after 3475 doing an OPEN. This is to ensure that the data for the OPENed 3476 file is still correctly reflected in the client's cache. This 3477 validation must be done at least when the client's OPEN 3478 operation includes DENY=WRITE or BOTH thus terminating a period 3479 in which other clients may have had the opportunity to open the 3480 file with WRITE access. Clients may choose to do the 3481 revalidation more often (i.e. at OPENs specifying DENY=NONE) to 3482 parallel the NFS version 3 protocol's practice for the benefit 3483 of users assuming this degree of cache revalidation. 3485 o Second, modified data must be flushed to the server before 3486 closing a file OPENed for write. This is complementary to the 3487 first rule. If the data is not flushed at CLOSE, the 3488 revalidation done after client OPENs as file is unable to 3489 achieve its purpose. The other aspect to flushing the data 3490 before close is that the data must be committed to stable 3491 storage before the CLOSE operation is requested by the client. 3492 In the case of a server reboot or restart and a CLOSEd file, it 3493 may not be possible to retransmit the data to be written to the 3494 file. Hence, this requirement. 3496 9.3.2. Data Caching and File Locking 3498 For those applications that choose to use file locking instead of 3499 share reservations to exclude inconsistent file access, there is an 3500 analogous set of constraints that apply to client side data caching. 3501 These rules are effective only if the file locking is used in a way 3502 that matches in an equivalent way the actual READ and WRITE 3503 operations executed. This is as opposed to file locking that is 3505 Draft Specification NFS version 4 Protocol January 2000 3507 based on pure convention. For example, it is possible to manipulate 3508 a two-megabyte file by dividing the file into two one-megabyte 3509 regions and protecting access to the two regions by file locks on 3510 bytes zero and one. A lock for write on byte zero of the file would 3511 represent the right to do READ and WRITE operations on the first 3512 region. A lock for write on byte one of the file would represent the 3513 right to do READ and WRITE operations on the second region. As long 3514 as all applications manipulating the file obey this convention, they 3515 will work on a local file system. However, they may not work with 3516 the NFS version 4 protocol unless clients refrain from data caching. 3518 The rules for data caching in the file locking environment are: 3520 o First, when a client obtains a file lock for a particular 3521 region, the data cache corresponding to that region (if any 3522 cache data exists) must be revalidated. If the change attribute 3523 indicates that the file may have been updated since the cached 3524 data was obtained, the client must flush or invalidate the 3525 cached data for the newly locked region. A client might choose 3526 to invalidate all of non-modified cached data that it has for 3527 the file but the only requirement for correct operation is to 3528 invalidate all of the data in the newly locked region. 3530 o Second, before releasing a write lock for a region, all modified 3531 data for that region must be flushed to the server. The 3532 modified data must also be written to stable storage. 3534 Note that flushing data to the server and the invalidation of cached 3535 data must reflect the actual byte ranges locked or unlocked. 3536 Rounding these up or down to reflect client cache block boundaries 3537 will cause problems if not carefully done. For example, writing a 3538 modified block when only half of that block is within an area being 3539 unlocked may cause invalid modification to the region outside the 3540 unlocked area. This, in turn, may be part of a region locked by 3541 another client. Clients can avoid this situation by synchronously 3542 performing portions of write operations that overlap that portion 3543 (initial or final) that is not a full block. Similarly, invalidating 3544 a locked area which is not an integral number of full buffer blocks 3545 would require the client to read one or two partial blocks from the 3546 server if the revalidation procedure shows that the data which the 3547 client possesses may not be valid. 3549 The data that is written to the server as a pre-requisite to the 3550 unlocking of a region must be written to stable storage. The client 3551 may accomplish this either with synchronous writes or by following 3552 asynchronous writes with a COMMIT operation. This is required 3553 because retransmission of the modified data after a server reboot 3554 might conflict with a lock held by another client. 3556 Draft Specification NFS version 4 Protocol January 2000 3558 A client implementation may choose to accommodate applications which 3559 use record locking in non-standard ways (e.g. using a record lock as 3560 a global semaphore) by flushing to the server more data upon an LOCKU 3561 than is covered by the locked range. This may include modified data 3562 within files other than the one for which the unlocks are being done. 3563 In such cases, the client must not interfere with applications whose 3564 READs and WRITEs are being done only within the bounds of record 3565 locks which the application holds. For example, an application locks 3566 a single byte of a file and proceeds to write that single byte. A 3567 client that chose to handle a LOCKU by flushing all modified data to 3568 the server could validly write that single byte in response to an 3569 unrelated unlock. However, it would not be valid to write the entire 3570 block in which that single written byte was located since it includes 3571 an area that is not locked and might be locked by another client. 3572 Client implementations can avoid this problem by dividing files with 3573 modified data into those for which all modifications are done to 3574 areas covered by an appropriate record lock and those for which there 3575 are modifications not covered by a record lock. Any writes done for 3576 the former class of files must not include areas not locked and thus 3577 not modified on the client. 3579 9.3.3. Data Caching and Mandatory File Locking 3581 Client side data caching needs to respect mandatory file locking when 3582 it is in effect. The presence of mandatory file locking for a given 3583 file is indicated in the result flags for an OPEN. When mandatory 3584 locking is in effect for a file, the client must check for an 3585 appropriate file lock for data being read or written. If a lock 3586 exists for the range being read or written, the client may satisfy 3587 the request using the client's validated cache. If an appropriate 3588 file lock is not held for the range of the read or write, the read or 3589 write request must not be satisfied by the client's cache and the 3590 request sent to the server for processing. When a read or write 3591 request partially overlaps a locked region, the request should be 3592 subdivided into multiple pieces with each region (locked or not) 3593 treated appropriately. 3595 9.3.4. Data Caching and File Identity 3597 When clients cache data, the file data needs to organized according 3598 to the file system object to which the data belongs. For NFS version 3599 3 clients, the typical practice has been to assume for the purpose of 3600 caching that distinct filehandles represent distinct file system 3601 objects. The client then has the choice to organize and maintain the 3602 data cache on this basis. 3604 Draft Specification NFS version 4 Protocol January 2000 3606 In the NFS version 4 protocol, there is now the possibility to have 3607 significant deviations from a "one filehandle per object" model 3608 because a filehandle may be constructed on the basis of the object's 3609 pathname. Therefore, clients need a reliable method to determine if 3610 two filehandles designate the same file system object. If clients 3611 were simply to assume that all distinct filehandles denote distinct 3612 objects and proceed to do data caching on this basis, caching 3613 inconsistencies would arise between the distinct client side objects 3614 which mapped to the same server side object. 3616 By providing a method to differentiate filehandles, the NFS version 4 3617 protocol alleviates a potential functional regression in comparison 3618 with the NFS version 3 protocol. Without this method, caching 3619 inconsistencies within the same client could occur and this has not 3620 been present in previous versions of the NFS protocol. Note that it 3621 is possible to have such inconsistencies with applications executing 3622 on multiple clients but that is not the issue being addressed here. 3624 For the purposes of data caching, the following steps allow an NFS 3625 version 4 client to determine whether two distinct filehandles denote 3626 the same server side object: 3628 o If GETATTR directed to two filehandles have different values of 3629 the fsid attribute, then the filehandles represent distinct 3630 objects. 3632 o If GETATTR for any file with an fsid that matches the fsid of 3633 the two filehandles in question returns a unique_handles 3634 attribute with a value of TRUE, then the two objects are 3635 distinct. 3637 o If GETATTR directed to the two filehandles does not return the 3638 fileid attribute for one or both of the handles, then the it 3639 cannot be determined whether the two objects are the same. 3640 Therefore, operations which depend on that knowledge (e.g. 3641 client side data caching) cannot be done reliably. 3643 o If GETATTR directed to the two filehandles returns different 3644 values for the fileid attribute, then they are distinct objects. 3646 o Otherwise they are the same object. 3648 9.4. Open Delegation 3650 When a file is being OPENed, the server may delegate further handling 3651 of opens and closes for that file to the opening client. Any such 3653 Draft Specification NFS version 4 Protocol January 2000 3655 delegation is recallable, since the circumstances that allowed for 3656 the delegation are subject to change. In particular, the server may 3657 receive a conflicting OPEN from another client, the server must 3658 recall the delegation before deciding whether the OPEN from the other 3659 client may be granted. Making a delegation is up to the server and 3660 clients should not assume that any particular OPEN either will or 3661 will not result in an open delegation. The following is a typical 3662 set of conditions that servers might use in deciding whether OPEN 3663 should be delegated: 3665 o The client must be able to respond to the server's callback 3666 requests. The server will use the CB_NULL procedure for a test 3667 of callback ability. 3669 o The client must have responded properly to previous recalls. 3671 o There must be no current open conflicting with the requested 3672 delegation. 3674 o There should be no current delegation that conflicts with the 3675 delegation being requested. 3677 o The probability of future conflicting open requests should be 3678 low based on the recent history of the file. 3680 o The existence of any server-specific semantics of OPEN/CLOSE 3681 that would make the required handling incompatible with the 3682 prescribed handling that the delegated client would apply (see 3683 below). 3685 There are two types of open delegations, read and write. A read open 3686 delegation allows a client to handle, on its own, requests to open a 3687 file for reading that do not deny read access to others. Multiple 3688 read open delegations may be outstanding simultaneously and do not 3689 conflict. A write open delegation allows the client to handle, on 3690 its own, all opens. Only one write open delegation may exist for a 3691 given file at a given time and it is inconsistent with any read open 3692 delegations. 3694 When a client has a read open delegation, it may not make any changes 3695 to the contents or attributes of the file but it is assured that no 3696 other client may do so. When a client has a write open delegation, 3697 it may modify the file data since no other client will be accessing 3698 the file's data. The client holding a write delegation may only 3699 affect file attributes which are intimately connected with the file 3700 data: object_size, time_modify, change. 3702 When a client has an open delegation, it does not send OPENs or 3704 Draft Specification NFS version 4 Protocol January 2000 3706 CLOSEs to the server but updates the appropriate status internally. 3707 For a read open delegation, opens that cannot be handled locally 3708 (opens for write or that deny read access) must be sent to the 3709 server. 3711 When an open delegation is made, the response to the OPEN contains an 3712 open delegation structure which specifies the following: 3714 o the type of delegation (read or write) 3716 o space limitation information to control flushing of data on 3717 close (write open delegation only, see the section "Open 3718 Delegation and Data Caching") 3720 o an nfsace4 specifying read and write permissions 3722 o a stateid to represent the delegation for READ and WRITE 3724 The stateid is separate and distinct from the stateid for the OPEN 3725 proper. The standard stateid, unlike the delegation stateid, is 3726 associated with a particular nfs_lockowner and will continue to be 3727 valid after the delegation is recalled and the file remains open. 3729 When a request internal to the client is made to open a file and open 3730 delegation is in effect, it will be accepted or rejected solely on 3731 the basis of the following conditions. Any requirement for other 3732 checks to be made by the delegate should result in open delegation 3733 being denied so that the checks can be made by the server itself. 3735 o The access and deny bits for the request and the file as 3736 described in the section "Share Reservations". 3738 o The read and write permissions as determined below. 3740 The nfsace4 passed with delegation can be used to avoid frequent 3741 ACCESS calls. The permission check should be as follows: 3743 o If the nfsace4 indicates that the open may be done, then it 3744 should be granted without reference to the server. 3746 o If the nfsace4 indicates that the open may not be done, then an 3747 ACCESS request must be sent to the server to obtain the 3748 definitive answer. 3750 The server may return an nfsace4 that is more restrictive than the 3751 actual ACL of the file. This includes an nfsace4 that specifies 3752 denial of all access. Note that some common practices such as 3754 Draft Specification NFS version 4 Protocol January 2000 3756 mapping the traditional user "root" to the user "nobody" may make it 3757 incorrect to return the actual ACL of the file in the delegation 3758 response. 3760 The use of delegation together with various other forms of caching 3761 creates the possibility that no server authentication will ever be 3762 performed for a given user since all of the user's requests might be 3763 satisfied locally. Where the client is depending on the server for 3764 authentication, the client should be sure authentication occurs for 3765 each user by use of the ACCESS operation. This should be the case 3766 even if an ACCESS operation would not be required otherwise. As 3767 mentioned before, the server may enforce frequent authentication by 3768 returning an nfsace4 denying all access with every open delegation. 3770 9.4.1. Open Delegation and Data Caching 3772 OPEN delegation allows much of the message overhead associated with 3773 the opening and closing files to be eliminated. An open when an open 3774 delegation is in effect does not require that a validation message be 3775 sent to the server. The continued endurance of the "read open 3776 delegation" provides a guarantee that no OPEN for write and thus no 3777 write has occurred. Similarly, when closing a file opened for write 3778 and if write open delegation is in effect, the data written does not 3779 have to be flushed to the server until the open delegation is 3780 recalled. The continued endurance of the open delegation provides a 3781 guarantee that no open and thus no read or write has been done by 3782 another client. 3784 For the purposes of open delegation, READs and WRITEs done without an 3785 OPEN are treated as the functional equivalents of a corresponding 3786 type of OPEN. This refers to the READs and WRITEs that use the 3787 special stateids consisting of all zero bits or all one bits. 3788 Therefore, READs or WRITEs with a special stateid done by another 3789 client will force the server to recall a write open delegation. A 3790 WRITE with a special stateid done by another client will force a 3791 recall of read open delegations. 3793 With delegations, a client is able to avoid writing data to the 3794 server when the CLOSE of a file is serviced. The CLOSE operation is 3795 the usual point at which the client is notified of a lack of stable 3796 storage for the modified file data generated by the application. At 3797 the CLOSE, file data is written to the server and through normal 3798 accounting the server is able to determine if the available file 3799 system space for the data has been exceeded (i.e. server returns 3800 NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. 3801 The introduction of delegations requires that a alternative method be 3802 in place for the same type of communication to occur between client 3804 Draft Specification NFS version 4 Protocol January 2000 3806 and server. 3808 In the delegation response, the server provides either the limit of 3809 the size of the file or the number of modified blocks and associated 3810 block size. The server must ensure that the client will be able to 3811 flush data to the server of a size equal to that provided in the 3812 original delegation. The server must make this assurance for all 3813 outstanding delegations. Therefore, the server must be careful in 3814 its management of available space for new or modified data taking 3815 into account available file system space and any applicable quotas. 3816 The server can recall delegations as a result of managing the 3817 available file system space. The client should abide by the server's 3818 state space limits for delegations. If the client exceeds the stated 3819 limits for the delegation, the server's behavior is undefined. 3821 Based on server conditions, quotas or available file system space, 3822 the server may grant write open delegations with very restrictive 3823 space limitations. The limitations may be defined in a way that will 3824 always force modified data to be flushed to the server on close. 3826 With respect to authentication, flushing modified data to the server 3827 after a CLOSE has occurred may be problematic. For example, the user 3828 of the application may have logged off of the client and unexpired 3829 authentication credentials may not be present. In this case, the 3830 client may need to take special care to ensure that local unexpired 3831 credentials will in fact be available. This may be accomplished by 3832 tracking the expiration time of credentials and flushing data well in 3833 advance of their expiration or by making private copies of 3834 credentials to assure their availability when needed. 3836 9.4.2. Open Delegation and File Locks 3838 When a client holds a write open delegation, lock operations are 3839 performed locally. This includes those required for mandatory file 3840 locking. This can be done since the delegation implies that there 3841 can be no conflicting locks. Similarly, all of the revalidations 3842 that would normally be associated with obtaining locks and the 3843 flushing of data associated with the releasing of locks need not be 3844 done. 3846 9.4.3. Recall of Open Delegation 3848 The following events necessitate recall of an open delegation: 3850 o Potentially conflicting OPEN request (or READ/WRITE done with 3851 "special" stateid) 3853 Draft Specification NFS version 4 Protocol January 2000 3855 o SETATTR issued by another client 3857 o REMOVE request for the file 3859 o RENAME request for the file as either source or target of the 3860 RENAME 3862 Whether a RENAME of a directory in the path leading to the file 3863 results in recall of an open delegation depends on the semantics of 3864 the server file system. If that file system denies such RENAMEs when 3865 a file is open, the recall must be performed to determine whether the 3866 file in question is, in fact, open. 3868 In addition to the situations above, the server may choose to recall 3869 open delegations at any time if resource constraints make it 3870 advisable to do so. Clients should always be prepared for the 3871 possibility of recall. 3873 The server needs to employ special handling for a GETATTR where the 3874 target is a file that has a write open delegation in effect. In this 3875 case, the client holding the delegation needs to be interrogated. 3876 The server will use a CB_GETATTR callback, if the GETATTR attribute 3877 bits include any of the attributes that a write open delegate may 3878 modify (object_size, time_modify, change). 3880 When a client receives a recall for an open delegation, it needs to 3881 update state on the server before returning the delegation. These 3882 same updates must be done whenever a client chooses to return a 3883 delegation voluntarily. The following items of state need to be 3884 dealt with: 3886 o If the file associated with the delegation is no longer open and 3887 no previous CLOSE operation has been sent to the server, a CLOSE 3888 operation must be sent to the server. 3890 o If file has other open references at the client, then OPEN 3891 operations must be sent to the server. The appropriate stateids 3892 will be provided by the server for subsequent use by the client 3893 since the delegation stateid will not longer be valid. These 3894 OPEN requests are done with the claim type of 3895 CLAIM_DELEGATE_CUR. This will allow the presentation of the 3896 delegation stateid so that the client can establish the 3897 appropriate rights to perform the OPEN. (see the section 3898 "Operation 18: OPEN" for details.) 3900 o If there are granted file locks, the corresponding LOCK 3901 operations need to be performed. This applies to the write open 3902 delegation case only. 3904 Draft Specification NFS version 4 Protocol January 2000 3906 o For a write open delegation, if, at the time of recall, if the 3907 file is not open for write, all modified data for the file must 3908 be flushed to the server. If the delegation had not existed, 3909 the client would have done this data flush before the CLOSE 3910 operation. 3912 o With the write open delegation in place, it is possible that the 3913 file was truncated during the duration of the delegation. For 3914 example, the truncation could have occurred as a result of an 3915 OPEN UNCHECKED with a object_size attribute value of zero. 3916 Therefore, if a truncation of the file has occurred and this 3917 operation has not been propagated to the server, the truncation 3918 must occur before any modified data is written to the server. 3920 o Any modified data for the file needs to be flushed to the the 3921 server. 3923 In the case of write open delegation, file locking imposes some 3924 additional requirements. The flushing of any modified data in any 3925 region for which a write lock was released while the write open 3926 delegation was in effect is what is required to precisely maintain 3927 the associated invariant. However, because the write open delegation 3928 implies no other locking by other clients, a simpler implementation 3929 is to flush all modified data for the file (as described just above) 3930 if any write lock has been released while the write open delegation 3931 was in effect. 3933 9.4.4. Delegation Revocation 3935 At the point a delegation is revoked, if there are associated opens 3936 on the client, the applications holding these opens need to be 3937 notified. This notification usually occurs by returning errors for 3938 READ/WRITE operations or when a close is attempted for the open file. 3940 If no opens exist for the file at the point the delegation is 3941 revoked, then notification of the revocation is unnecessary. 3942 However, if there is modified data present at the client for the 3943 file, the user of the application should be notified. Unfortunately, 3944 it may not be possible to notify the user since active applications 3945 may not be present at the client. See the section "Revocation 3946 Recovery for Write Open Delegation" for additional details. 3948 9.5. Data Caching and Revocation 3950 When locks and delegations are revoked, the assumptions upon which 3951 successful caching depend are no longer guaranteed. The owner of the 3953 Draft Specification NFS version 4 Protocol January 2000 3955 locks or share reservations which have been revoked needs to be 3956 notified. This notification includes applications with a file open 3957 that has a corresponding delegation which has been revoked. Cached 3958 data associated with the revocation must be removed from the client. 3959 In the case of modified data existing in the client's cache, that 3960 data must be removed from the client without it being written to the 3961 server. 3963 Notification to a lock owner will in many cases consist of simply 3964 returning an error on the next and all subsequent READs/WRITEs to the 3965 open file or on the close. Where the methods available to a client 3966 to make such notification impossible because errors for certain 3967 operations may not be returned, more drastic action such as signals 3968 or process termination may be appropriate. The justification for 3969 this is that an invariant for which an application depends on may be 3970 violated. Depending on how errors are typically treated for the 3971 client operating environment, further levels of notification 3972 including logging, console messages, and GUI pop-ups may be 3973 appropriate. 3975 9.5.1. Revocation Recovery for Write Open Delegation 3977 Revocation recovery for a write open delegation poses the special 3978 issue of modified data in the client cache while the file is not 3979 open. In this situation, any client which does not flush modified 3980 data to the server on each close must ensure that the user receives 3981 appropriate notification of the failure as a result of the 3982 revocation. Since such situations may require human action to 3983 correct problems, notification schemes in which the appropriate user 3984 or administrator is notified may be necessary. Logging and console 3985 messages are typical examples. 3987 If there is modified data on the client, it must not be flushed 3988 normally to the server. A client may attempt to provide a copy of 3989 the file data as modified during the delegation under a different 3990 name in the file system name space to ease recovery. Unless the 3991 client can determine that the file has not modified by any other 3992 client, this technique must be limited to situations in which a 3993 client has a complete cached copy of the file in question. Use of 3994 such a technique may be limited to files under a certain size or may 3995 only be used when sufficient disk space is guaranteed to be available 3996 within the target file system and when the client has sufficient 3997 buffering resources to keep the cached copy available until it is 3998 properly stored to the target file system. 4000 Draft Specification NFS version 4 Protocol January 2000 4002 9.6. Attribute Caching 4004 The attributes discussed in this section do not include named 4005 attributes. Individual named attributes are analogous to files and 4006 caching of the data for these needs to be handled just as data 4007 caching is for ordinary files. Similarly, LOOKUP results from an 4008 OPENATTR directory are to be cached on the same basis as any other 4009 pathnames and similarly for directory contents. 4011 Clients may cache file attributes obtained from the server and use 4012 them to avoid subsequent GETATTR requests. Such caching is write 4013 through in that modification to file attributes is always done by 4014 means of requests to the server and should not be done locally and 4015 cached. The exception to this are modifications to attributes that 4016 are intimately connected with data caching. Therefore, extending a 4017 file by writing data to the local data cache is reflected immediately 4018 in the object_size as seen on the client without this change being 4019 immediately reflected on the server. Normally such changes are not 4020 propagated directly to the server but when the modified data is 4021 flushed to the server, analogous attribute changes are made on the 4022 server. When open delegation is in effect, the modified attributes 4023 may be returned to the server in the response to a CB_RECALL call. 4025 The result of local caching of attributes is that the attribute 4026 caches maintained on individual clients will not be coherent. Changes 4027 made in one order on the server may be seen in a different order on 4028 one client and in a third order on a different client. 4030 The typical file system application programming interfaces do not 4031 provide means to atomically modify or interrogate attributes for 4032 multiple files at the same time. The following rules provide an 4033 environment where the potential incoherences mentioned above can be 4034 reasonably managed. These rules are derived from the practice of 4035 previous NFS protocols. 4037 o All attributes for a given file (per-fsid attributes excepted) 4038 are cached as a unit at the client so that no non- 4039 serializability can arise within the context of a single file. 4041 o An upper time boundary is maintained on how long a client cache 4042 entry can be kept without being refreshed from the server. 4044 o When operations are performed that change attributes at the 4045 server, the updated attribute set is requested as part of the 4046 containing RPC. This includes directory operations that update 4047 attributes indirectly. This is accomplished by following the 4048 modifying operation with a GETATTR operation and then using the 4049 results of the GETATTR to update the client's cached attributes. 4051 Draft Specification NFS version 4 Protocol January 2000 4053 Note that if the full set of attributes to be cached is requested by 4054 READDIR, the results can be cached by the client on the same basis as 4055 attributes obtained via GETATTR. 4057 A client may validate its cached version of attributes for a file by 4058 fetching only the change attribute and assuming that if the change 4059 attribute has the same value as it did when the attributes were 4060 cached, then no attributes have changed. The possible exception is 4061 the attribute time_access. 4063 9.7. Name Caching 4065 The results of LOOKUP and READDIR operations may be cached to avoid 4066 the cost of subsequent LOOKUP operations. Just as in the case of 4067 attribute caching, inconsistencies may arise among the various client 4068 caches. To mitigate the effects of these inconsistencies and given 4069 the context of typical file system APIs, the following rules should 4070 be followed: 4072 o The results of unsuccessful LOOKUPs should not be cached, unless 4073 they are specifically reverified at the point of use. 4075 o An upper time boundary is maintained on how long a client name 4076 cache entry can be kept without verifying that the entry has not 4077 been made invalid by a directory change operation performed by 4078 another client. 4080 When a client is not making changes to a directory for which there 4081 exist name cache entries, the client needs to periodically fetch 4082 attributes for that directory to ensure that it is not being 4083 modified. After determining that no modification has occurred, the 4084 expiration time for the associated name cache entries may be updated 4085 to be the current time plus the name cache staleness bound. 4087 When a client is making changes to a given directory, it needs to 4088 determine whether there have been changes made to the directory by 4089 other clients. It does this by using the change attribute as 4090 reported before and after the directory operation in the associated 4091 change_info4 value returned for the operation. The server is able to 4092 communicate to the client whether the change_info4 data is provided 4093 atomically with respect to the directory operation. If the change 4094 values are provided atomically, the client is then able to compare 4095 the pre-operation change value with the change value in the client's 4096 name cache. If the comparison indicates that the directory was 4097 updated by another client, the name cache associated with the 4098 modified directory is purged from the client. If the comparison 4099 indicates no modification, the name cache can be updated on the 4101 Draft Specification NFS version 4 Protocol January 2000 4103 client to reflect the directory operation and the associated timeout 4104 extended. The post-operation change value needs to be saved as the 4105 basis for future change_info4 comparisons. 4107 As demonstrated by the scenario above, name caching requires that the 4108 client revalidate name cache data by inspecting the change attribute 4109 of a directory at the point when the name cache item was cached. 4110 This requires that the server update the change attribute for 4111 directories when the contents of the corresponding directory is 4112 modified. For a client to use the change_info4 information 4113 appropriately and correctly, the server must report the pre and post 4114 operation change attribute values atomically. When the server is 4115 unable to report the before and after values atomically with respect 4116 to the directory operation, the server must indicate that fact in the 4117 change_info4 return value. When the information is not atomically 4118 reported, the client should not assume that other clients have not 4119 changed the directory. 4121 9.8. Directory Caching 4123 The results of READDIR operations may be used to avoid subsequent 4124 READDIR operations. Just as in the cases of attribute and name 4125 caching inconsistencies may arise among the various client caches. 4126 To mitigate the effects of these inconsistencies and given the 4127 context of typical file system APIs, the following rules should be 4128 followed: 4130 o Cached READDIR information for a directory which is not obtained 4131 in a single READDIR operation must always be a consistent 4132 snapshot of directory contents. This is determined by using a 4133 GETATTR before the first READDIR and after the last of READDIR 4134 that contributes to the cache. 4136 o An upper time boundary is maintained to indicate the length of 4137 time a directory cache entry is considered valid before the 4138 client must revalidate the cached information. 4140 The revalidation technique parallels that discussed in the case of 4141 name caching. When the client is not changing the directory in 4142 question, checking the change attribute of the directory with GETATTR 4143 is adequate. The lifetime of the cache entry can be extended at 4144 these checkpoints. When a client is modifying the directory, the 4145 client needs to use the change_info4 data to determine whether there 4146 are other clients modifying the directory. If it is determined that 4147 no other client modifications are occurring, the client may update 4148 its directory cache to reflect its own changes. 4150 Draft Specification NFS version 4 Protocol January 2000 4152 As demonstrated previously, directory caching requires that the 4153 client revalidate directory cache data by inspecting the change 4154 attribute of a directory at the point when the directory was cached. 4155 This requires that the server update the change attribute for 4156 directories when the contents of the corresponding directory is 4157 modified. For a client to use the change_info4 information 4158 appropriately and correctly, the server must report the pre and post 4159 operation change attribute values atomically. When the server is 4160 unable to report the before and after values atomically with respect 4161 to the directory operation, the server must indicate that fact in the 4162 change_info4 return value. When the information is not atomically 4163 reported, the client should not assume that other clients have not 4164 changed the directory. 4166 Draft Specification NFS version 4 Protocol January 2000 4168 10. Minor Versioning 4170 To address the requirement of an NFS protocol that can evolve as the 4171 need arises, the NFS version 4 protocol contains the rules and 4172 framework to allow for future minor changes or versioning. 4174 The base assumption with respect to minor versioning is that any 4175 future accepted minor version must follow the IETF process and be 4176 documented in a standards track RFC. Therefore, each minor version 4177 number will correspond to an RFC. Minor version zero of the NFS 4178 version 4 protocol is represented by this RFC. The COMPOUND 4179 procedure will support the encoding of the minor version being 4180 requested by the client. 4182 The following items represent the basic rules for the development of 4183 minor versions. Note that a future minor version may decide to 4184 modify or add to the following rules as part of the minor version 4185 definition. 4187 1 Procedures are not added or deleted 4189 To maintain the general RPC model, NFS version 4 minor versions 4190 will not add or delete procedures from the NFS program. 4192 2 Minor versions may add operations to the COMPOUND and 4193 CB_COMPOUND procedures. 4195 The addition of operations to the COMPOUND and CB_COMPOUND 4196 procedures does not affect the RPC model. 4198 2.1 Minor versions may append attributes to GETATTR4args, bitmap4, 4199 and GETATTR4res. 4201 This allows for the expansion of the attribute model to allow 4202 for future growth or adaptation. 4204 2.2 Minor version X must append any new attributes after the last 4205 documented attribute. 4207 Since attribute results are specified as an opaque array of 4208 per-attribute XDR encoded results, the complexity of adding new 4209 attributes in the midst of the current definitions will be too 4210 burdensome. 4212 Draft Specification NFS version 4 Protocol January 2000 4214 3 Minor versions must not modify the structure of an existing 4215 operation's arguments or results. 4217 Again the complexity of handling multiple structure definitions 4218 for a single operation is too burdensome. New operations should 4219 be added instead of modifying existing structures for a minor 4220 version. 4222 This rule does not preclude the following adaptations in a minor 4223 version. 4225 o adding bits to flag fields such as new attributes to 4226 GETATTR's bitmap4 data type 4228 o adding bits to existing attributes like ACLs that have flag 4229 words 4231 o extending enumerated types (including NFS4ERR_*) with new 4232 values 4234 4 Minor versions may not modify the structure of existing 4235 attributes. 4237 5 Minor versions may not delete operations. 4239 This prevents the potential reuse of a particular operation 4240 "slot" in a future minor version. 4242 6 Minor versions may not delete attributes. 4244 7 Minor versions may not delete flag bits or enumeration values. 4246 8 Minor versions may declare an operation as mandatory to NOT 4247 implement. 4249 Specifying an operation as "mandatory to not implement" is 4250 equivalent to obsoleting an operation. For the client, it means 4251 that the operation should not be sent to the server. For the 4252 server, an NFS error can be returned as opposed to "dropping" 4253 the request as an XDR decode error. This approach allows for 4254 the obsolescence of an operation while maintaining its structure 4255 so that a future minor version can reintroduce the operation. 4257 Draft Specification NFS version 4 Protocol January 2000 4259 8.1 Minor versions may declare attributes mandatory to NOT 4260 implement. 4262 8.2 Minor versions may declare flag bits or enumeration values as 4263 mandatory to NOT implement. 4265 9 Minor versions may downgrade features from mandatory to 4266 recommended, or recommended to optional. 4268 10 Minor versions may upgrade features from optional to recommended 4269 or recommended to mandatory. 4271 11 A client and server that support minor version X must support 4272 minor versions 0 (zero) through X-1 as well. 4274 12 No new features may be introduced as mandatory in a minor 4275 version. 4277 This rule allows for the introduction of new functionality and 4278 forces the use of implementation experience before designating a 4279 feature as mandatory. 4281 13 A client MUST NOT attempt to use a stateid, file handle, or 4282 similar returned object from the COMPOUND procedure with minor 4283 version X for another COMPOUND procedure with minor version Y, 4284 where X != Y. 4286 Draft Specification NFS version 4 Protocol January 2000 4288 11. Internationalization 4290 The primary issue in which NFS needs to deal with 4291 internationalization, or i18n, is with respect to file names and 4292 other strings as used within the protocol. NFS' choice of string 4293 representation must allow reasonable name/string access to clients 4294 which use various languages. The UTF-8 encoding allows for this type 4295 of access and follows the policy described in "IETF Policy on 4296 Character Sets and Languages", [RFC2277]. This choice is explained 4297 further in the following. 4299 11.1. Universal Versus Local Character Sets 4301 [RFC1345] describes a table of 16 bit characters for many different 4302 languages (the bit encodings match Unicode, though of course RFC1345 4303 is somewhat out of date with respect to current Unicode assignments). 4304 Each character from each language has a unique 16 bit value in the 16 4305 bit character set. Thus this table can be thought of as a universal 4306 character set. [RFC1345] then talks about groupings of subsets of the 4307 entire 16 bit character set into "Charset Tables". For example one 4308 might take all the Greek characters from the 16 bit table (which are 4309 are consecutively allocated), and normalize their offsets to a table 4310 that fits in 7 bits. Thus it is determined that "lower case alpha" 4311 is in the same position as "upper case a" in the US-ASCII table, and 4312 "upper case alpha" is in the same position as "lower case a" in the 4313 US-ASCII table. 4315 These normalized subset character sets can be thought of as "local 4316 character sets", suitable for an operating system locale. 4318 Local character sets are not suitable for the NFS protocol. Consider 4319 someone who creates a file with a name in a Swedish character set. If 4320 someone else later goes to access the file with their locale set to 4321 the Swedish language, then there are no problems. But if someone in 4322 say the US-ASCII locale goes to access the file, the file name will 4323 look very different, because the Swedish characters in the 7 bit 4324 table will now be represented in US-ASCII characters on the display. 4325 It would be preferable to give the US-ASCII user a way to display the 4326 file name using Swedish glyphs. In order to do that, the NFS protocol 4327 would have to include the locale with the file name on each operation 4328 to create a file. 4330 But then what of the situation when there is a path name on the 4331 server like: 4333 /component-1/component-2/component-3 4335 Each component could have been created with a different locale. If 4337 Draft Specification NFS version 4 Protocol January 2000 4339 one issues CREATE with multi-component path name, and if some of the 4340 leading components already exist, what is to be done with the 4341 existing components? Is the current locale attribute replaced with 4342 the user's current one? These types of situations quickly become too 4343 complex when there is an alternate solution. 4345 If NFS V4 used a universal 16 bit or 32 bit character set (or a 4346 encoding of a 16 bit or 32 bit character set into octets), then the 4347 server and client need not care if the locale of the user accessing 4348 the file is different than the locale of the user who created the 4349 file. The unique 16 bit or 32 bit encoding of the character allows 4350 for determination of what language the character is from and also how 4351 to display that character on the client. The server need not know 4352 what locales are used. 4354 11.2. Overview of Universal Character Set Standards 4356 The previous section makes a case for using a universal character set 4357 in NFS version 4. This section makes the case for using UTF-8 as the 4358 specific universal character set for NFS version 4. 4360 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 4361 Unicode, and UCS-*. There are two standards bodies managing universal 4362 code sets: 4364 o ISO/IEC which has the standard 10646-1 4366 o Unicode which has the Unicode standard 4368 Both standards bodies have pledged to track each other's assignments 4369 of character codes. 4371 The following is a brief analysis of the various standards. 4373 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 4374 multi-octet character set called the Universal Character 4375 Set (UCS), which encompasses most of the world's writing 4376 systems." 4378 UCS-2 a two octet per character encoding that addresses the first 4379 2^16 characters of UCS. Currently there are no UCS 4380 characters beyond that range. 4382 UCS-4 a four octet per character encoding that permits the 4383 encoding of up to 2^31 characters. 4385 Draft Specification NFS version 4 Protocol January 2000 4387 UTF UCS transformation format. 4389 UTF-1 Only historical interest; it has been removed from 10646-1 4391 UTF-7 Encodes the entire "repertoire" of UCS "characters using 4392 only octets with the higher order bit clear". [RFC2152] 4393 describes UTF-7. UTF-7 accomplishes this by reserving one 4394 of the 7bit US-ASCII characters as a "shift" character to 4395 indicate non-US-ASCII characters. 4397 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 4398 characters are encoded as before unchanged. Any octet with 4399 the high bit cleared can only mean a US-ASCII character. 4400 The high bit set means that a UCS character is being 4401 encoded. 4403 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 4404 reserved range in UCS-2. 4406 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 4408 Up to the present time, changes in Unicode and amendments 4409 to ISO/IEC 10646 have tracked each other, so that the 4410 character repertoires and code point assignments have 4411 remained in sync. The relevant standardization committees 4412 have committed to maintain this very useful synchronism. 4414 11.3. Difficulties with UCS-4, UCS-2, Unicode 4416 Adapting existing applications, and file systems to multi-octet 4417 schemes like UCS and Unicode can be difficult. A significant amount 4418 of code has been written to process streams of bytes. Also there are 4419 many existing stored objects described with 7 bit or 8 bit 4420 characters. Doubling or quadrupling the bandwidth and storage 4421 requirements seems like an expensive way to accomplish I18N. 4423 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 4424 enough but, according to [Unicode1], 49,194 Unicode characters are 4425 already assigned. According to [Unicode2] there are still more 4426 languages that need to be added. 4428 Draft Specification NFS version 4 Protocol January 2000 4430 11.4. UTF-8 and its solutions 4432 UTF-8 solves problems for NFS that exist with the use of UCS and 4433 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 4434 that will be compact for most users. The encoding table from UCS-4 to 4435 UTF-8, as copied from [RFC2279]: 4437 UCS-4 range (hex.) UTF-8 octet sequence (binary) 4438 0000 0000-0000 007F 0xxxxxxx 4439 0000 0080-0000 07FF 110xxxxx 10xxxxxx 4440 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 4442 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 4443 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4444 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4445 10xxxxxx 4447 See [RFC2279] for precise encoding and decoding rules. Note because 4448 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 4449 for the reserved range between D800 and DFFF. 4451 Note that the 16 bit UCS or Unicode characters require no more than 3 4452 octets to encode into UTF-8 4454 Interestingly, UTF-8 has room to handle characters larger than 31 4455 bits, because the leading octet of form: 4457 1111111x 4459 is not defined. If needed, ISO could either use that octet to 4460 indicate a sequence of an encoded 8 octet character, or perhaps use 4461 11111110 to permit the next octet to indicate an even more expandable 4462 character set. 4464 So using UTF-8 to represent character encodings means never having to 4465 run out of room. 4467 Draft Specification NFS version 4 Protocol January 2000 4469 12. Error Definitions 4471 NFS error numbers are assigned to failed operations within a compound 4472 request. A compound request contains a number of NFS operations that 4473 have their results encoded in sequence in a compound reply. The 4474 results of successful operations will consist of an NFS4_OK status 4475 followed by the encoded results of the operation. If an NFS 4476 operation fails, an error status will be entered in the reply and the 4477 compound request will be terminated. 4479 A description of each defined error follows: 4481 NFS4_OK Indicates the operation completed successfully. 4483 NFS4ERR_ACCES Permission denied. The caller does not have the 4484 correct permission to perform the requested 4485 operation. Contrast this with NFS4ERR_PERM, 4486 which restricts itself to owner or privileged 4487 user permission failures. 4489 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 4490 internal consistency checks. 4492 NFS4ERR_BADTYPE An attempt was made to create an object of a 4493 type not supported by the server. 4495 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 4497 NFS4ERR_BAD_SEQID The sequence number in a locking request is 4498 neither the next expected number or the last 4499 number processed. 4501 NFS4ERR_BAD_STATEID A stateid generated by the current server 4502 instance, but which does not designate any 4503 locking state (either current or superseded) 4504 for a current lockowner-file pair, was used. 4506 NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a 4507 client id is already in use by another client. 4509 NFS4ERR_DELAY The server initiated the request, but was not 4510 able to complete it in a timely fashion. The 4511 client should wait and then try the request 4512 with a new RPC transaction ID. For example, 4513 this error should be returned from a server 4514 that supports hierarchical storage and receives 4516 Draft Specification NFS version 4 Protocol January 2000 4518 a request to process a file that has been 4519 migrated. In this case, the server should start 4520 the immigration process and respond to client 4521 with this error. This error may also occur 4522 when a necessary delegation recall makes 4523 processing a request in a timely fashion 4524 impossible. 4526 NFS4ERR_DENIED An attempt to lock a file is denied. Since 4527 this may be a temporary condition, the client 4528 is encouraged to retry the lock request until 4529 the lock is accepted. 4531 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The 4532 user's resource limit on the server has been 4533 exceeded. 4535 NFS4ERR_EXIST File exists. The file specified already exists. 4537 NFS4ERR_EXPIRED A lease has expired that is being used in the 4538 current procedure. 4540 NFS4ERR_FBIG File too large. The operation would have caused 4541 a file to grow beyond the server's limit. 4543 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 4544 expired at the server. 4546 NFS4ERR_GRACE The server is in its recovery or grace period 4547 which should match the lease period of the 4548 server. 4550 NFS4ERR_INVAL Invalid argument or unsupported argument for an 4551 operation. Two examples are attempting a 4552 READLINK on an object other than a symbolic 4553 link or attempting to SETATTR a time field on a 4554 server that does not support this operation. 4556 NFS4ERR_IO I/O error. A hard error (for example, a disk 4557 error) occurred while processing the requested 4558 operation. 4560 NFS4ERR_ISDIR Is a directory. The caller specified a 4561 directory in a non-directory operation. 4563 NFS4ERR_LOCKED A read or write operation was attempted on a 4564 locked file. 4566 Draft Specification NFS version 4 Protocol January 2000 4568 NFS4ERR_LOCK_RANGE A lock request is operating on a sub-range of a 4569 current lock for the lock owner and the server 4570 does not support this type of request. 4572 NFS4ERR_MINOR_VERS_MISMATCH 4573 The server has received a request that 4574 specifies an unsupported minor version. The 4575 server must return a COMPOUND4res with a zero 4576 length operations result array. 4578 NFS4ERR_MLINK Too many hard links. 4580 NFS4ERR_MOVED The filesystem which contains the current 4581 filehandle object has been relocated or 4582 migrated to another server. The client may 4583 obtain the new filesystem location by obtaining 4584 the "fs_locations" attribute for the current 4585 filehandle. For further discussion, refer to 4586 the section "Filesystem Migration or 4587 Relocation". 4589 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 4591 NFS4ERR_NODEV No such device. 4593 NFS4ERR_NOENT No such file or directory. The file or 4594 directory name specified does not exist. 4596 NFS4ERR_NOFILEHANDLE The logical current file handle value has not 4597 been set properly. This may be a result of a 4598 malformed COMPOUND operation (i.e. no PUTFH or 4599 PUTROOTFH before an operation that requires the 4600 current file handle be set). 4602 NFS4ERR_NOSPC No space left on device. The operation would 4603 have caused the server's file system to exceed 4604 its limit. 4606 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 4607 directory in a directory operation. 4609 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 4610 was not empty. 4612 NFS4ERR_NOTSUPP Operation is not supported. 4614 NFS4ERR_NOT_SAME This error is returned by the VERIFY operation 4615 to signify that the attributes compared were 4617 Draft Specification NFS version 4 Protocol January 2000 4619 not the same as provided in the client's 4620 request. 4622 NFS4ERR_NOT_SYNC Update synchronization mismatch was detected 4623 during a SETATTR operation. 4625 NFS4ERR_NXIO I/O error. No such device or address. 4627 NFS4ERR_OLD_STATEID A stateid which designates the locking state 4628 for a lockowner-file at an earlier time was 4629 used. 4631 NFS4ERR_PERM Not owner. The operation was not allowed 4632 because the caller is either not a privileged 4633 user (root) or not the owner of the target of 4634 the operation. 4636 NFS4ERR_READDIR_NOSPC The encoded response to a READDIR request 4637 exceeds the size limit set by the initial 4638 request. 4640 NFS4ERR_RESOURCE For the processing of the COMPOUND procedure, 4641 the server may exhaust available resources and 4642 can not continue processing procedures within 4643 the COMPOUND operation. This error will be 4644 returned from the server in those instances of 4645 resource exhaustion related to the processing 4646 of the COMPOUND procedure. 4648 NFS4ERR_ROFS Read-only file system. A modifying operation 4649 was attempted on a read-only file system. 4651 NFS4ERR_SAME This error is returned by the NVERIFY operation 4652 to signify that the attributes compared were 4653 the same as provided in the client's request. 4655 NFS4ERR_SERVERFAULT An error occurred on the server which does not 4656 map to any of the legal NFS version 4 protocol 4657 error values. The client should translate this 4658 into an appropriate error. UNIX clients may 4659 choose to translate this to EIO. 4661 NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share 4662 reservation has failed because of a share 4663 conflict. 4665 NFS4ERR_STALE Invalid file handle. The file handle given in 4666 the arguments was invalid. The file referred to 4668 Draft Specification NFS version 4 Protocol January 2000 4670 by that file handle no longer exists or access 4671 to it has been revoked. 4673 NFS4ERR_STALE_CLIENTID A clientid not recognized by the server was 4674 used in a locking or SETCLIENTID_CONFIRM 4675 request. 4677 NFS4ERR_STALE_STATEID A stateid generated by an earlier server 4678 instance was used. 4680 NFS4ERR_SYMLINK The current file handle provided for a LOOKUP 4681 is not a directory but a symbolic link. 4683 NFS4ERR_TOOSMALL Buffer or request is too small. 4685 NFS4ERR_WRONGSEC The security mechanism being used by the client 4686 for the procedure does not match the server's 4687 security policy. The client should change the 4688 security mechanism being used and retry the 4689 operation. 4691 NFS4ERR_XDEV Attempt to do a cross-device hard link. 4693 Draft Specification NFS version 4 Protocol January 2000 4695 13. NFS Version 4 Requests 4697 For the NFS version 4 RPC program, there are two traditional RPC 4698 procedures: NULL and COMPOUND. All other functionality is defined as 4699 a set of operations and these operations are defined in normal 4700 XDR/RPC syntax and semantics. However, these operations are 4701 encapsulated within the COMPOUND procedure. This requires that the 4702 client combine one or more of the NFS version 4 operations into a 4703 single request. 4705 The NFS4_CALLBACK program is used to provide server to client 4706 signaling and is constructed in a similar fashion as the NFS version 4707 4 program. The procedures CB_NULL and CB_COMPOUND are defined in the 4708 same way as NULL and COMPOUND are within the NFS program. The 4709 CB_COMPOUND request also encapsulates the remaining operations of the 4710 NFS4_CALLBACK program. There is no predefined RPC program number for 4711 the NFS4_CALLBACK program. It is up to the client to specify a 4712 program number in the "transient" program range. The program and 4713 port number of the NFS4_CALLBACK program are provided by the client 4714 as part of the SETCLIENTID operation and therefore is fixed for the 4715 life of the client instantiation. 4717 13.1. Compound Procedure 4719 The COMPOUND procedure provides the opportunity for better 4720 performance within high latency networks. The client can avoid 4721 cumulative latency of multiple RPCs by combining multiple dependent 4722 operations into a single COMPOUND procedure. A compound operation 4723 may provide for protocol simplification by allowing the client to 4724 combine basic procedures into a single request that is customized for 4725 the client's environment. 4727 The CB_COMPOUND procedure precisely parallels the features of 4728 COMPOUND as described above. 4730 The basics of the COMPOUND procedures construction is: 4732 +-----------+-----------+-----------+-- 4733 | op + args | op + args | op + args | 4734 +-----------+-----------+-----------+-- 4736 and the reply looks like this: 4738 +------------+-----------------------+-----------------------+-- 4739 |last status | status + op + results | status + op + results | 4740 +------------+-----------------------+-----------------------+-- 4742 Draft Specification NFS version 4 Protocol January 2000 4744 13.2. Evaluation of a Compound Request 4746 The server will process the COMPOUND procedure by evaluating each of 4747 the operations within the COMPOUND procedure in order. Each 4748 component operation consists of a 32 bit operation code, followed by 4749 the argument of length determined by the type of operation. The 4750 results of each operation are encoded in sequence into a reply 4751 buffer. The results of each operation are preceded by the opcode and 4752 a status code (normally zero). If an operation results in a non-zero 4753 status code, the status will be encoded and evaluation of the 4754 compound sequence will halt and the reply will be returned. 4756 There are no atomicity requirements for the operations contained 4757 within the COMPOUND procedure. The operations being evaluated as 4758 part of a COMPOUND request may be evaluated simultaneously with other 4759 COMPOUND requests that the server receives. 4761 It is the client's responsibility for recovering from any partially 4762 completed COMPOUND procedure. Partially completed COMPOUND 4763 procedures may occur at any point due to errors such as 4764 NFS4ERR_RESOURCE and NFS4ERR_LONG_DELAY. This may occur even given 4765 an otherwise valid operation string. Further, a server reboot which 4766 occurs in the middle of processing a COMPOUND procedure may leave the 4767 client with the difficult task of determining how far COMPOUND 4768 processing has proceeded. Therefore, the client should avoid overly 4769 complex COMPOUND procedures in the event of the failure of an 4770 operation within the procedure. 4772 Each operation assumes a "current" and "saved" filehandle that is 4773 available as part of the execution context of the compound request. 4774 Operations may set, change, or return the current filehandle. The 4775 "saved" filehandle is used for temporary storage of a filehandle 4776 value and as operands for the RENAME and LINK operations. 4778 13.3. Operation Values 4780 The operations encoded in the COMPOUND procedure are identified by 4781 operation values. To avoid overlap with the RPC procedure numbers, 4782 operations 0 (zero) and 1 are not defined. Operation 2 is not 4783 defined but reserved for future use with minor versioning. 4785 Draft Specification NFS version 4 Protocol January 2000 4787 14. NFS Version 4 Procedures 4789 14.1. Procedure 0: NULL - No Operation 4791 SYNOPSIS 4793 4795 ARGUMENT 4797 void; 4799 RESULT 4801 void; 4803 DESCRIPTION 4805 Standard NULL procedure. Void argument, void response. This 4806 procedure has no functionality associated with it. Because of this 4807 it is sometimes used to measure the overhead of processing a 4808 service request. Therefore, the server should ensure that no 4809 unnecessary work is done in servicing this procedure. 4811 ERRORS 4813 None. 4815 Draft Specification NFS version 4 Protocol January 2000 4817 14.2. Procedure 1: COMPOUND - Compound Operations 4819 SYNOPSIS 4821 compoundargs -> compoundres 4823 ARGUMENT 4825 union nfs_argop4 switch (nfs_opnum4 argop) { 4826 case : ; 4827 ... 4828 }; 4830 struct COMPOUND4args { 4831 utf8string tag; 4832 uint32_t minorversion; 4833 nfs_argop4 argarray<>; 4834 }; 4836 RESULT 4838 union nfs_resop4 switch (nfs_opnum4 resop){ 4839 case : ; 4840 ... 4841 }; 4843 struct COMPOUND4res { 4844 nfsstat4 status; 4845 utf8string tag; 4846 nfs_resop4 resarray<>; 4847 }; 4849 DESCRIPTION 4851 The COMPOUND procedure is used to combine one or more of the NFS 4852 operations into a single RPC request. The main NFS RPC program has 4853 two main procedures: NULL and COMPOUND. All other operations use 4854 the COMPOUND procedure as a wrapper. 4856 The COMPOUND procedure is used to combine individual operations 4857 into a single RPC request. The server interprets each of the 4858 operations in turn. If an operation is executed by the server and 4859 the status of that operation is NFS4_OK, then the next operation in 4861 Draft Specification NFS version 4 Protocol January 2000 4863 the COMPOUND procedure is executed. The server continues this 4864 process until there are no more operations to be executed or one of 4865 the operations has a status value other than NFS4_OK. 4867 In the processing of the COMPOUND procedure, the server may find 4868 that it does not have the available resources to execute any or all 4869 of the operations within the COMPOUND sequence. In this case, the 4870 error NFS4ERR_RESOURCE will be returned for the particular 4871 operation within the COMPOUND procedure where the resource 4872 exhaustion occurred. This assumes that all previous operations 4873 within the COMPOUND sequence have been evaluated successfully. The 4874 results for all of the evaluated operations must be returned to the 4875 client. 4877 The COMPOUND arguments contain a "minorversion" field. The initial 4878 and default value for this field is 0 (zero). This field will be 4879 used by future minor versions such that the client can communicate 4880 to the server what minor version is being requested. If the server 4881 receives a COMPOUND procedure with a minorversion field value that 4882 it does not support, the server MUST return an error of 4883 NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata array. 4885 Contained within the COMPOUND results is a "status" field. If the 4886 results array length is non-zero, this status must be equivalent to 4887 the status of the last operation that was executed within the 4888 COMPOUND procedure. Therefore, if an operation incurred an error 4889 then the "status" value will be the same error value as is being 4890 returned for the operation that failed. 4892 Note that operations, 0 (zero) and 1 (one) are not defined for the 4893 COMPOUND procedure. If the server receives an operation array with 4894 either of these included, an error of NFS4ERR_NOTSUPP must be 4895 returned. Operation 2 is not defined but reserved for future 4896 definition and use with minor versioning. If the server receives a 4897 operation array that contains operation 2 and the minorversion 4898 field has a value of 0 (zero), an error of NFS4ERR_NOTSUPP is 4899 returned. If an operation array contains an operation 2 and the 4900 minorversion field is non-zero and the server does not support the 4901 minor version, the server returns an error of 4902 NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the 4903 NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other 4904 errors. 4906 IMPLEMENTATION 4908 Note that the definition of the "tag" in both the request and 4910 Draft Specification NFS version 4 Protocol January 2000 4912 response are left to the implementor. It may be used to summarize 4913 the content of the compound request for the benefit of packet 4914 sniffers and engineers debugging implementations. 4916 Since an error of any type may occur after only a portion of the 4917 operations have been evaluated, the client must be prepared to 4918 recover from any failure. If the source of an NFS4ERR_RESOURCE 4919 error was a complex or lengthy set of operations, it is likely that 4920 if the number of operations were reduced the server would be able 4921 to evaluate them successfully. Therefore, the client is 4922 responsible for dealing with this type of complexity in recovery. 4924 ERRORS 4926 All errors defined in the protocol 4928 Draft Specification NFS version 4 Protocol January 2000 4930 14.2.1. Operation 3: ACCESS - Check Access Rights 4932 SYNOPSIS 4934 (cfh), accessreq -> supported, accessrights 4936 ARGUMENT 4938 const ACCESS4_READ = 0x00000001; 4939 const ACCESS4_LOOKUP = 0x00000002; 4940 const ACCESS4_MODIFY = 0x00000004; 4941 const ACCESS4_EXTEND = 0x00000008; 4942 const ACCESS4_DELETE = 0x00000010; 4943 const ACCESS4_EXECUTE = 0x00000020; 4945 struct ACCESS4args { 4946 /* CURRENT_FH: object */ 4947 uint32_t access; 4948 }; 4950 RESULT 4952 struct ACCESS4resok { 4953 uint32_t supported; 4954 uint32_t access; 4955 }; 4957 union ACCESS4res switch (nfsstat4 status) { 4958 case NFS4_OK: 4959 ACCESS4resok resok4; 4960 default: 4961 void; 4962 }; 4964 DESCRIPTION 4966 ACCESS determines the access rights that a user, as identified by 4967 the credentials in the RPC request, has with respect to the file 4968 system object specified by the current filehandle. The client 4969 encodes the set of access rights that are to be checked in the bit 4970 mask "access". The server checks the permissions encoded in the 4971 bit mask. If a status of NFS4_OK is returned, two bit masks are 4972 included in the response. The first, "supported", represents the 4974 Draft Specification NFS version 4 Protocol January 2000 4976 access rights for which the server can verify reliably. The 4977 second, "access", represents the access rights available to the 4978 user for the filehandle provided. On success, the current 4979 filehandle retains its value. 4981 Note that the supported field will contain only as many values as 4982 was originally sent in the arguments. For example, if the client 4983 sends an ACCESS operation with only the ACCESS4_READ value set and 4984 the server supports this value, the server will return only 4985 ACCESS4_READ even if it could have reliably checked other values. 4987 The results of this operation are necessarily advisory in nature. 4988 A return status of NFS4_OK and the appropriate bit set in the bit 4989 mask does not imply that such access will be allowed to the file 4990 system object in the future. This is because access rights can be 4991 revoked by the server at any time. 4993 The following access permissions may be requested: 4995 ACCESS4_READ Read data from file or read a directory. 4997 ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- 4998 directory objects). 5000 ACCESS4_MODIFY Rewrite existing file data or modify existing 5001 directory entries. 5003 ACCESS4_EXTEND Write new data or add directory entries. 5005 ACCESS4_DELETE Delete an existing directory entry (no meaning for 5006 non-directory objects). 5008 ACCESS4_EXECUTE Execute file (no meaning for a directory). 5010 IMPLEMENTATION 5012 In general, it is not sufficient for the client to attempt to 5013 deduce access permissions by inspecting the uid, gid, and mode 5014 fields in the file attributes or by attempting to interpret the 5015 contents of the ACL attribute. This is because the server may 5016 perform uid or gid mapping or enforce additional access control 5017 restrictions. It is also possible that the server may not be in 5018 the same ID space as the client. In these cases (and perhaps 5019 others), the client can not reliably perform an access check with 5020 only current file attributes. 5022 Draft Specification NFS version 4 Protocol January 2000 5024 In the NFS version 2 protocol, the only reliable way to determine 5025 whether an operation was allowed was to try it and see if it 5026 succeeded or failed. Using the ACCESS procedure in the NFS version 5027 4 protocol, the client can ask the server to indicate whether or 5028 not one or more classes of operations are permitted. The ACCESS 5029 operation is provided to allow clients to check before doing a 5030 series of operations. This is useful in operating systems (such as 5031 UNIX) where permission checking is done only when a directory is 5032 opened. The intent is to make the behavior of opening a remote 5033 file more consistent with the behavior of opening a local file. 5035 For the NFS version 4 protocol, the use of the ACCESS procedure 5036 when opening a regular file is deprecated in favor of using OPEN. 5038 The information returned by the server in response to an ACCESS 5039 call is not permanent. It was correct at the exact time that the 5040 server performed the checks, but not necessarily afterwards. The 5041 server can revoke access permission at any time. 5043 The client should use the effective credentials of the user to 5044 build the authentication information in the ACCESS request used to 5045 determine access rights. It is the effective user and group 5046 credentials that are used in subsequent read and write operations. 5048 Many implementations do not directly support the ACCESS_DELETE 5049 permission. Operating systems like UNIX will ignore the 5050 ACCESS_DELETE bit if set on an access request on a non-directory 5051 object. In these systems, delete permission on a file is 5052 determined by the access permissions on the directory in which the 5053 file resides, instead of being determined by the permissions of the 5054 file itself. Therefore, the mask returned enumerating which access 5055 rights can be determined will have the ACCESS_DELETE value set to 5056 0. This indicates to the client that the server was unable to 5057 check that particular access right. The ACCESS_DELETE bit in the 5058 access mask returned will then be ignored by the client. 5060 ERRORS 5062 NFS4ERR_ACCES 5063 NFS4ERR_BADHANDLE 5064 NFS4ERR_DELAY 5065 NFS4ERR_FHEXPIRED 5066 NFS4ERR_IO 5067 NFS4ERR_MOVED 5068 NFS4ERR_NOFILEHANDLE 5069 NFS4ERR_RESOURCE 5070 NFS4ERR_SERVERFAULT 5072 Draft Specification NFS version 4 Protocol January 2000 5074 NFS4ERR_STALE 5075 NFS4ERR_WRONGSEC 5077 Draft Specification NFS version 4 Protocol January 2000 5079 14.2.2. Operation 4: CLOSE - Close File 5081 SYNOPSIS 5083 (cfh), stateid -> stateid 5085 ARGUMENT 5087 struct CLOSE4args { 5088 /* CURRENT_FH: object */ 5089 seqid4 seqid 5090 stateid4 stateid; 5091 }; 5093 RESULT 5095 union CLOSE4res switch (nfsstat4 status) { 5096 case NFS4_OK: 5097 stateid4 stateid; 5098 default: 5099 void; 5100 }; 5102 DESCRIPTION 5104 The CLOSE operation releases share reservations for the file as 5105 specified by the current filehandle. The share reservations and 5106 other state information released at the server as a result of this 5107 CLOSE is only associated with the supplied stateid. The sequence 5108 id provides for the correct ordering. State associated with other 5109 OPENs is not affected. 5111 If record locks are held, the client SHOULD release all locks 5112 before issuing a CLOSE. The server MAY free all outstanding locks 5113 on CLOSE but some servers may not support the CLOSE of a file that 5114 still has record locks held. The server MUST return failure if any 5115 locks would exist after the CLOSE. 5117 On success, the current filehandle retains its value. 5119 IMPLEMENTATION 5121 Draft Specification NFS version 4 Protocol January 2000 5123 ERRORS 5125 NFS4ERR_BADHANDLE 5126 NFS4ERR_BAD_SEQID 5127 NFS4ERR_BAD_STATEID 5128 NFS4ERR_DELAY 5129 NFS4ERR_EXPIRED 5130 NFS4ERR_FHEXPIRED 5131 NFS4ERR_GRACE 5132 NFS4ERR_INVAL 5133 NFS4ERR_MOVED 5134 NFS4ERR_NOFILEHANDLE 5135 NFS4ERR_OLD_STATEID 5136 NFS4ERR_RESOURCE 5137 NFS4ERR_SERVERFAULT 5138 NFS4ERR_STALE 5139 NFS4ERR_STALE_STATEID 5141 Draft Specification NFS version 4 Protocol January 2000 5143 14.2.3. Operation 5: COMMIT - Commit Cached Data 5145 SYNOPSIS 5147 (cfh), offset, count -> verifier 5149 ARGUMENT 5151 struct COMMIT4args { 5152 /* CURRENT_FH: file */ 5153 offset4 offset; 5154 count4 count; 5155 }; 5157 RESULT 5159 struct COMMIT4resok { 5160 verifier4 writeverf; 5161 }; 5163 union COMMIT4res switch (nfsstat4 status) { 5164 case NFS4_OK: 5165 COMMIT4resok resok4; 5166 default: 5167 void; 5168 }; 5170 DESCRIPTION 5172 The COMMIT operation forces or flushes data to stable storage for 5173 the file specified by the current file handle. The flushed data is 5174 that which was previously written with a WRITE operation which had 5175 the stable field set to UNSTABLE4. 5177 The offset specifies the position within the file where the flush 5178 is to begin. An offset value of 0 (zero) means to flush data 5179 starting at the beginning of the file. The count specifies the 5180 number of bytes of data to flush. If count is 0 (zero), a flush 5181 from offset to the end of the file is done. 5183 The server returns a write verifier upon successful completion of 5184 the COMMIT. The write verifier is used by the client to determine 5185 if the server has restarted or rebooted between the initial 5186 WRITE(s) and the COMMIT. The client does this by comparing the 5187 write verifier returned from the initial writes and the verifier 5189 Draft Specification NFS version 4 Protocol January 2000 5191 returned by the COMMIT procedure. The server must vary the value 5192 of the write verifier at each server event or instantiation that 5193 may lead to a loss of uncommitted data. Most commonly this occurs 5194 when the server is rebooted; however, other events at the server 5195 may result in uncommitted data loss as well. 5197 On success, the current filehandle retains its value. 5199 IMPLEMENTATION 5201 The COMMIT procedure is similar in operation and semantics to the 5202 POSIX fsync(2) system call that synchronizes a file's state with 5203 the disk (file data and metadata is flushed to disk or stable 5204 storage). COMMIT performs the same operation for a client, flushing 5205 any unsynchronized data and metadata on the server to the server's 5206 disk or stable storage for the specified file. Like fsync(2), it 5207 may be that there is some modified data or no modified data to 5208 synchronize. The data may have been synchronized by the server's 5209 normal periodic buffer synchronization activity. COMMIT should 5210 return NFS4_OK, unless there has been an unexpected error. 5212 COMMIT differs from fsync(2) in that it is possible for the client 5213 to flush a range of the file (most likely triggered by a buffer- 5214 reclamation scheme on the client before file has been completely 5215 written). 5217 The server implementation of COMMIT is reasonably simple. If the 5218 server receives a full file COMMIT request, that is starting at 5219 offset 0 and count 0, it should do the equivalent of fsync()'ing 5220 the file. Otherwise, it should arrange to have the cached data in 5221 the range specified by offset and count to be flushed to stable 5222 storage. In both cases, any metadata associated with the file must 5223 be flushed to stable storage before returning. It is not an error 5224 for there to be nothing to flush on the server. This means that 5225 the data and metadata that needed to be flushed have already been 5226 flushed or lost during the last server failure. 5228 The client implementation of COMMIT is a little more complex. 5229 There are two reasons for wanting to commit a client buffer to 5230 stable storage. The first is that the client wants to reuse a 5231 buffer. In this case, the offset and count of the buffer are sent 5232 to the server in the COMMIT request. The server then flushes any 5233 cached data based on the offset and count, and flushes any metadata 5234 associated with the file. It then returns the status of the flush 5235 and the write verifier. The other reason for the client to 5236 generate a COMMIT is for a full file flush, such as may be done at 5237 close. In this case, the client would gather all of the buffers 5239 Draft Specification NFS version 4 Protocol January 2000 5241 for this file that contain uncommitted data, do the COMMIT 5242 operation with an offset of 0 and count of 0, and then free all of 5243 those buffers. Any other dirty buffers would be sent to the server 5244 in the normal fashion. 5246 After a buffer is written by the client with the stable parameter 5247 set to UNSTABLE4, the buffer must be considered as modified by the 5248 client until the buffer has either been flushed via a COMMIT 5249 operation or written via a WRITE operation with stable parameter 5250 set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer 5251 from being freed and reused before the data can be flushed to 5252 stable storage on the server. 5254 When a response is returned from either a WRITE or a COMMIT 5255 operation and it contains a write verifier that is different than 5256 previously returned by the server, the client will need to 5257 retransmit all of the buffers containing uncommitted cached data to 5258 the server. How this is to be done is up to the implementor. If 5259 there is only one buffer of interest, then it should probably be 5260 sent back over in a WRITE request with the appropriate stable 5261 parameter. If there is more than one buffer, it might be 5262 worthwhile retransmitting all of the buffers in WRITE requests with 5263 the stable parameter set to UNSTABLE4 and then retransmitting the 5264 COMMIT operation to flush all of the data on the server to stable 5265 storage. The timing of these retransmissions is left to the 5266 implementor. 5268 The above description applies to page-cache-based systems as well 5269 as buffer-cache-based systems. In those systems, the virtual 5270 memory system will need to be modified instead of the buffer cache. 5272 ERRORS 5274 NFS4ERR_ACCES 5275 NFS4ERR_BADHANDLE 5276 NFS4ERR_FHEXPIRED 5277 NFS4ERR_IO 5278 NFS4ERR_LOCKED 5279 NFS4ERR_MOVED 5280 NFS4ERR_NOFILEHANDLE 5281 NFS4ERR_RESOURCE 5282 NFS4ERR_ROFS 5283 NFS4ERR_SERVERFAULT 5284 NFS4ERR_STALE 5285 NFS4ERR_WRONGSEC 5287 Draft Specification NFS version 4 Protocol January 2000 5289 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 5291 SYNOPSIS 5293 (cfh), name, type -> (cfh), change_info 5295 ARGUMENT 5297 union createtype4 switch (nfs_ftype4 type) { 5298 case NF4LNK: 5299 linktext4 linkdata; 5300 case NF4BLK: 5301 case NF4CHR: 5302 specdata4 devdata; 5303 case NF4SOCK: 5304 case NF4FIFO: 5305 case NF4DIR: 5306 void; 5307 }; 5309 struct CREATE4args { 5310 /* CURRENT_FH: directory for creation */ 5311 component4 objname; 5312 createtype4 objtype; 5313 }; 5315 RESULT 5317 struct CREATE4resok { 5318 change_info4 cinfo; 5319 }; 5321 union CREATE4res switch (nfsstat4 status) { 5322 case NFS4_OK: 5323 CREATE4resok resok4; 5324 default: 5325 void; 5326 }; 5328 DESCRIPTION 5330 The CREATE operation creates a non-regular file object in a 5331 directory with a given name. The OPEN procedure MUST be used to 5332 create a regular file. 5334 Draft Specification NFS version 4 Protocol January 2000 5336 The objname specifies the name for the new object. If the objname 5337 has a length of 0 (zero), the error NFS4ERR_INVAL will be returned. 5338 The objtype determines the type of object to be created: directory, 5339 symlink, etc. 5341 If an object of the same name already exists in the directory, the 5342 server will return the error NFS4ERR_EXIST. 5344 For the directory where the new file object was created, the server 5345 returns change_info4 information in cinfo. With the atomic field 5346 of the change_info4 struct, the server will indicate if the before 5347 and after change attributes were obtained atomically with respect 5348 to the file object creation. 5350 If the objname has a length of 0 (zero), or if objname does not 5351 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5352 returned. 5354 The current filehandle is replaced by that of the new object. 5356 IMPLEMENTATION 5358 If the client desires to set attribute values after the create, a 5359 SETATTR operation can be added to the COMPOUND request so that the 5360 appropriate attributes will be set. 5362 ERRORS 5364 NFS4ERR_ACCES 5365 NFS4ERR_BADHANDLE 5366 NFS4ERR_BADTYPE 5367 NFS4ERR_DQUOT 5368 NFS4ERR_EXIST 5369 NFS4ERR_FHEXPIRED 5370 NFS4ERR_INVAL 5371 NFS4ERR_IO 5372 NFS4ERR_MOVED 5373 NFS4ERR_NAMETOOLONG 5374 NFS4ERR_NOFILEHANDLE 5375 NFS4ERR_NOSPC 5376 NFS4ERR_NOTDIR 5377 NFS4ERR_NOTSUPP 5378 NFS4ERR_RESOURCE 5379 NFS4ERR_ROFS 5380 NFS4ERR_SERVERFAULT 5381 NFS4ERR_STALE 5383 Draft Specification NFS version 4 Protocol January 2000 5385 NFS4ERR_WRONGSEC 5387 Draft Specification NFS version 4 Protocol January 2000 5389 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery 5391 SYNOPSIS 5393 clientid -> 5395 ARGUMENT 5397 struct DELEGPURGE4args { 5398 clientid4 clientid; 5399 }; 5401 RESULT 5403 struct DELEGPURGE4res { 5404 nfsstat4 status; 5405 }; 5407 DESCRIPTION 5409 Purges all of the delegations awaiting recovery for a given client. 5410 This is useful for clients which do not commit delegation 5411 information to stable storage to indicate that conflicting requests 5412 need not be delayed by the server awaiting recovery of delegation 5413 information. 5415 This operation should also be used by clients which do have 5416 delegation information on stable storage after doing all of 5417 delegation recovery that is needed. Using DELEGPURGE will prevent 5418 any delegations which were made by the server but were not sent to 5419 the client and committed to stable storage from holding up other 5420 clients making conflicting requests. 5422 ERRORS 5424 NFS4ERR_RESOURCE 5425 NFS4ERR_SERVERFAULT 5426 NFS4ERR_STALE_CLIENTID 5428 Draft Specification NFS version 4 Protocol January 2000 5430 14.2.6. Operation 8: DELEGRETURN - Return Delegation 5432 SYNOPSIS 5434 stateid -> 5436 ARGUMENT 5438 struct DELEGRETURN4args { 5439 stateid4 stateid; 5440 }; 5442 RESULT 5444 struct DELEGRETURN4res { 5445 nfsstat4 status; 5446 }; 5448 DESCRIPTION 5450 Returns the delegation represented by the given stateid. 5452 ERRORS 5454 NFS4ERR_BAD_STATEID 5455 NFS4ERR_OLD_STATEID 5456 NFS4ERR_RESOURCE 5457 NFS4ERR_SERVERFAULT 5458 NFS4ERR_STALE_STATEID 5460 Draft Specification NFS version 4 Protocol January 2000 5462 14.2.7. Operation 9: GETATTR - Get Attributes 5464 SYNOPSIS 5466 (cfh), attrbits -> attrbits, attrvals 5468 ARGUMENT 5470 struct GETATTR4args { 5471 /* CURRENT_FH: directory or file */ 5472 bitmap4 attr_request; 5473 }; 5475 RESULT 5477 struct GETATTR4resok { 5478 fattr4 obj_attributes; 5479 }; 5481 union GETATTR4res switch (nfsstat4 status) { 5482 case NFS4_OK: 5483 GETATTR4resok resok4; 5484 default: 5485 void; 5486 }; 5488 DESCRIPTION 5490 The GETATTR operation will obtain attributes for the file system 5491 object specified by the current filehandle. The client sets a bit 5492 in the bitmap argument for each attribute value that it would like 5493 the server to return. The server returns an attribute bitmap that 5494 indicates the attribute values for which it was able to return, 5495 followed by the attribute values ordered lowest attribute number 5496 first. 5498 The server must return a value for each attribute that the client 5499 requests if the attribute is supported by the server. If the 5500 server does not support an attribute or cannot approximate a useful 5501 value then it must not return the attribute value and must not set 5502 the attribute bit in the result bitmap. The server must return an 5503 error if it supports an attribute but cannot obtain its value. In 5504 that case no attribute values will be returned. 5506 All servers must support the mandatory attributes as specified in 5508 Draft Specification NFS version 4 Protocol January 2000 5510 the section "File Attributes". 5512 On success, the current filehandle retains its value. 5514 IMPLEMENTATION 5516 ERRORS 5518 NFS4ERR_ACCES 5519 NFS4ERR_BADHANDLE 5520 NFS4ERR_DELAY 5521 NFS4ERR_FHEXPIRED 5522 NFS4ERR_INVAL 5523 NFS4ERR_IO 5524 NFS4ERR_MOVED 5525 NFS4ERR_NOFILEHANDLE 5526 NFS4ERR_RESOURCE 5527 NFS4ERR_SERVERFAULT 5528 NFS4ERR_STALE 5529 NFS4ERR_WRONGSEC 5531 Draft Specification NFS version 4 Protocol January 2000 5533 14.2.8. Operation 10: GETFH - Get Current Filehandle 5535 SYNOPSIS 5537 (cfh) -> filehandle 5539 ARGUMENT 5541 /* CURRENT_FH: */ 5542 void; 5544 RESULT 5546 struct GETFH4resok { 5547 nfs_fh4 object; 5548 }; 5550 union GETFH4res switch (nfsstat4 status) { 5551 case NFS4_OK: 5552 GETFH4resok resok4; 5553 default: 5554 void; 5555 }; 5557 DESCRIPTION 5559 This operation returns the current filehandle value. 5561 On success, the current filehandle retains its value. 5563 IMPLEMENTATION 5565 Operations that change the current filehandle like LOOKUP or CREATE 5566 do not automatically return the new filehandle as a result. For 5567 instance, if a client needs to lookup a directory entry and obtain 5568 its filehandle then the following request is needed. 5570 PUTFH (directory filehandle) 5571 LOOKUP (entry name) 5572 GETFH 5574 ERRORS 5576 Draft Specification NFS version 4 Protocol January 2000 5578 NFS4ERR_BADHANDLE 5579 NFS4ERR_FHEXPIRED 5580 NFS4ERR_MOVED 5581 NFS4ERR_NOFILEHANDLE 5582 NFS4ERR_RESOURCE 5583 NFS4ERR_SERVERFAULT 5584 NFS4ERR_STALE 5585 NFS4ERR_WRONGSEC 5587 Draft Specification NFS version 4 Protocol January 2000 5589 14.2.9. Operation 11: LINK - Create Link to a File 5591 SYNOPSIS 5593 (sfh), (cfh), newname -> (cfh), change_info 5595 ARGUMENT 5597 struct LINK4args { 5598 /* SAVED_FH: source object */ 5599 /* CURRENT_FH: target directory */ 5600 component4 newname; 5601 }; 5603 RESULT 5605 struct LINK4resok { 5606 change_info4 cinfo; 5607 }; 5609 union LINK4res switch (nfsstat4 status) { 5610 case NFS4_OK: 5611 LINK4resok resok4; 5612 default: 5613 void; 5614 }; 5616 DESCRIPTION 5618 The LINK operation creates an additional newname for the file 5619 represented by the saved filehandle, as set by the SAVEFH 5620 operation, in the directory represented by the current filehandle. 5621 The existing file and the target directory must reside within the 5622 same file system on the server. On success the current filehandle 5623 represents the object to which a new link was created. 5625 For the target directory, the server returns change_info4 5626 information in cinfo. With the atomic field of the change_info4 5627 struct, the server will indicate if the before and after change 5628 attributes were obtained atomically with respect to the link 5629 creation. 5631 If the newname has a length of 0 (zero), or if newname does not 5632 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5633 returned. 5635 Draft Specification NFS version 4 Protocol January 2000 5637 IMPLEMENTATION 5639 Changes to any property of the "hard" linked files are reflected in 5640 all of the linked files. When a link is made to a file, the 5641 attributes for the file should have a value for numlinks that is 5642 one greater than the value before the LINK operation. 5644 The comments under RENAME regarding object and target residing on 5645 the same file system apply here as well. The comments regarding the 5646 target name applies as well. 5648 ERRORS 5650 NFS4ERR_ACCES 5651 NFS4ERR_BADHANDLE 5652 NFS4ERR_DELAY 5653 NFS4ERR_DQUOT 5654 NFS4ERR_EXIST 5655 NFS4ERR_FHEXPIRED 5656 NFS4ERR_INVAL 5657 NFS4ERR_IO 5658 NFS4ERR_MLINK 5659 NFS4ERR_MOVED 5660 NFS4ERR_NAMETOOLONG 5661 NFS4ERR_NOSPC 5662 NFS4ERR_NOTDIR 5663 NFS4ERR_NOTSUPP 5664 NFS4ERR_RESOURCE 5665 NFS4ERR_ROFS 5666 NFS4ERR_SERVERFAULT 5667 NFS4ERR_STALE 5668 NFS4ERR_WRONGSEC 5669 NFS4ERR_XDEV 5671 Draft Specification NFS version 4 Protocol January 2000 5673 14.2.10. Operation 12: LOCK - Create Lock 5675 SYNOPSIS 5677 (cfh) type, seqid, reclaim, owner, offset, length -> stateid, 5678 access 5680 ARGUMENT 5682 enum nfs4_lock_type { 5683 READ_LT = 1, 5684 WRITE_LT = 2, 5685 READW_LT = 3, /* blocking read */ 5686 WRITEW_LT = 4 /* blocking write */ 5687 }; 5689 struct LOCK4args { 5690 /* CURRENT_FH: file */ 5691 nfs_lock_type4 locktype; 5692 seqid4 seqid; 5693 bool reclaim; 5694 stateid4 stateid; 5695 offset4 offset; 5696 length4 length; 5697 }; 5699 RESULT 5701 struct LOCK4denied { 5702 nfs_lockowner4 owner; 5703 offset4 offset; 5704 length4 length; 5705 }; 5707 union LOCK4res switch (nfsstat4 status) { 5708 case NFS4_OK: 5709 stateid4 stateid; 5710 case NFS4ERR_DENIED: 5711 LOCK4denied denied; 5712 default: 5713 void; 5714 }; 5716 DESCRIPTION 5718 Draft Specification NFS version 4 Protocol January 2000 5720 The LOCK operation requests a record lock for the byte range 5721 specified by the offset and length parameters. The lock type is 5722 also specified to be one of the nfs4_lock_types. If this is a 5723 reclaim request, the reclaim parameter will be TRUE; 5725 Bytes in a file may be locked even if those bytes are not currently 5726 allocated to the file. To lock the file from a specific offset 5727 through the end-of-file (no matter how long the file actually is) 5728 use a length field with all bits set to 1 (one). To lock the 5729 entire file, use an offset of 0 (zero) and a length with all bits 5730 set to 1. A length of 0 is reserved and should not be used. 5732 In the case that the lock is denied, the the owner, offset, and 5733 length of the conflicting lock are returned. 5735 On success, the current filehandle retains its value. 5737 IMPLEMENTATION 5739 If the server is unable to determine the exact offset and length of 5740 the conflicting lock, the same offset and length that were provided 5741 in the arguments should be returned in the denied results. The 5742 File Locking section contains a full description of this and the 5743 other file locking operations. 5745 ERRORS 5747 NFS4ERR_ACCES 5748 NFS4ERR_BADHANDLE 5749 NFS4ERR_BAD_SEQID 5750 NFS4ERR_BAD_STATEID 5751 NFS4ERR_DELAY 5752 NFS4ERR_DENIED 5753 NFS4ERR_EXPIRED 5754 NFS4ERR_FHEXPIRED 5755 NFS4ERR_GRACE 5756 NFS4ERR_INVAL 5757 NFS4ERR_ISDIR 5758 NFS4ERR_LOCK_RANGE 5759 NFS4ERR_MOVED 5760 NFS4ERR_NOFILEHANDLE 5761 NFS4ERR_OLD_STATEID 5762 NFS4ERR_RESOURCE 5763 NFS4ERR_SERVERFAULT 5764 NFS4ERR_STALE 5765 NFS4ERR_STALE_CLIENTID 5767 Draft Specification NFS version 4 Protocol January 2000 5769 NFS4ERR_STALE_STATEID 5770 NFS4ERR_WRONGSEC 5772 Draft Specification NFS version 4 Protocol January 2000 5774 14.2.11. Operation 13: LOCKT - Test For Lock 5776 SYNOPSIS 5778 (cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED -> 5779 owner} 5781 ARGUMENT 5783 struct LOCKT4args { 5784 /* CURRENT_FH: file */ 5785 nfs_lock_type4 locktype; 5786 nfs_lockowner4 owner; 5787 offset4 offset; 5788 length4 length; 5789 }; 5791 RESULT 5793 union LOCKT4res switch (nfsstat4 status) { 5794 case NFS4ERR_DENIED: 5795 LOCK4denied denied; 5796 case NFS4_OK: 5797 void; 5798 default: 5799 void; 5800 }; 5802 DESCRIPTION 5804 The LOCKT operation tests the lock as specified in the arguments. 5805 If a conflicting lock exists, the owner, offset, and length of the 5806 conflicting lock are returned; if no lock is held, nothing other 5807 than NFS4_OK is returned. 5809 On success, the current filehandle retains its value. 5811 IMPLEMENTATION 5813 If the server is unable to determine the exact offset and length of 5814 the conflicting lock, the same offset and length that were provided 5815 in the arguments should be returned in the denied results. The 5816 File Locking section contains further discussion of the file 5818 Draft Specification NFS version 4 Protocol January 2000 5820 locking mechanisms. 5822 ERRORS 5824 NFS4ERR_ACCES 5825 NFS4ERR_BADHANDLE 5826 NFS4ERR_DELAY 5827 NFS4ERR_DENIED 5828 NFS4ERR_FHEXPIRED 5829 NFS4ERR_GRACE 5830 NFS4ERR_INVAL 5831 NFS4ERR_ISDIR 5832 NFS4ERR_LOCK_RANGE 5833 NFS4ERR_MOVED 5834 NFS4ERR_NOFILEHANDLE 5835 NFS4ERR_RESOURCE 5836 NFS4ERR_SERVERFAULT 5837 NFS4ERR_STALE 5838 NFS4ERR_STALE_CLIENTID 5839 NFS4ERR_WRONGSEC 5841 Draft Specification NFS version 4 Protocol January 2000 5843 14.2.12. Operation 14: LOCKU - Unlock File 5845 SYNOPSIS 5847 (cfh) type, seqid, stateid, offset, length -> stateid 5849 ARGUMENT 5851 struct LOCKU4args { 5852 /* CURRENT_FH: file */ 5853 nfs_lock_type4 type; 5854 seqid4 seqid; 5855 stateid4 stateid; 5856 offset4 offset; 5857 length4 length; 5858 }; 5860 RESULT 5862 union LOCKU4res switch (nfsstat4 status) { 5863 case NFS4_OK: 5864 stateid4 stateid; 5865 default: 5866 void; 5867 }; 5869 DESCRIPTION 5871 The LOCKU operation unlocks the record lock specified by the 5872 parameters. 5874 On success, the current filehandle retains its value. 5876 IMPLEMENTATION 5878 The File Locking section contains a full description of this and 5879 the other file locking procedures. 5881 ERRORS 5883 NFS4ERR_ACCES 5884 NFS4ERR_BADHANDLE 5885 NFS4ERR_BAD_SEQID 5887 Draft Specification NFS version 4 Protocol January 2000 5889 NFS4ERR_BAD_STATEID 5890 NFS4ERR_EXPIRED 5891 NFS4ERR_FHEXPIRED 5892 NFS4ERR_GRACE 5893 NFS4ERR_INVAL 5894 NFS4ERR_LOCK_RANGE 5895 NFS4ERR_MOVED 5896 NFS4ERR_NOFILEHANDLE 5897 NFS4ERR_OLD_STATEID 5898 NFS4ERR_RESOURCE 5899 NFS4ERR_SERVERFAULT 5900 NFS4ERR_STALE 5901 NFS4ERR_STALE_CLIENTID 5902 NFS4ERR_STALE_STATEID 5904 Draft Specification NFS version 4 Protocol January 2000 5906 14.2.13. Operation 15: LOOKUP - Lookup Filename 5908 SYNOPSIS 5910 (cfh), filenames -> (cfh) 5912 ARGUMENT 5914 struct LOOKUP4args { 5915 /* CURRENT_FH: directory */ 5916 pathname4 path; 5917 }; 5919 RESULT 5921 struct LOOKUP4res { 5922 /* CURRENT_FH: object */ 5923 nfsstat4 status; 5924 }; 5926 DESCRIPTION 5928 This operation LOOKUPs or finds a file system object starting from 5929 the directory specified by the current filehandle. LOOKUP 5930 evaluates the pathname contained in the array of names and obtains 5931 a new current filehandle from the final name. All but the final 5932 name in the list must be the names of directories. 5934 If the pathname cannot be evaluated either because a component does 5935 not exist or because the client does not have permission to 5936 evaluate a component of the path, then an error will be returned 5937 and the current filehandle will be unchanged. 5939 If the path is a zero length array, if any component does not obey 5940 the UTF-8 definition, or if any component in the path is of zero 5941 length, the error NFS4ERR_INVAL will be returned. 5943 IMPLEMENTATION 5945 If the client prefers a partial evaluation of the path then a 5946 sequence of LOOKUP operations can be substituted e.g. 5948 Draft Specification NFS version 4 Protocol January 2000 5950 PUTFH (directory filehandle) 5951 LOOKUP "pub" "foo" "bar" 5952 GETFH 5954 or 5956 PUTFH (directory filehandle) 5957 LOOKUP "pub" 5958 GETFH 5959 LOOKUP "foo" 5960 GETFH 5961 LOOKUP "bar" 5962 GETFH 5964 NFS version 4 servers depart from the semantics of previous NFS 5965 versions in allowing LOOKUP requests to cross mountpoints on the 5966 server. The client can detect a mountpoint crossing by comparing 5967 the fsid attribute of the directory with the fsid attribute of the 5968 directory looked up. If the fsids are different then the new 5969 directory is a server mountpoint. Unix clients that detect a 5970 mountpoint crossing will need to mount the server's filesystem. 5972 Servers that limit NFS access to "shares" or "exported" filesystems 5973 should provide a pseudo-filesystem into which the exported 5974 filesystems can be integrated, so that clients can browse the 5975 server's name space. The clients view of a pseudo filesystem will 5976 be limited to paths that lead to exported filesystems. 5978 Note: previous versions of the protocol assigned special semantics 5979 to the names "." and "..". NFS version 4 assigns no special 5980 semantics to these names. The LOOKUPP operator must be used to 5981 lookup a parent directory. 5983 Note that this procedure does not follow symbolic links. The 5984 client is responsible for all parsing of filenames including 5985 filenames that are modified by symbolic links encountered during 5986 the lookup process. 5988 If the current file handle supplied is not a directory but a 5989 symbolic link, the error NFS4ERR_SYMLINK is returned as the error. 5990 For all other non-directory file types, the error NFS4ERR_NOTDIR is 5991 returned. 5993 ERRORS 5995 NFS4ERR_ACCES 5997 Draft Specification NFS version 4 Protocol January 2000 5999 NFS4ERR_BADHANDLE 6000 NFS4ERR_FHEXPIRED 6001 NFS4ERR_INVAL 6002 NFS4ERR_IO 6003 NFS4ERR_MOVED 6004 NFS4ERR_NAMETOOLONG 6005 NFS4ERR_NOENT 6006 NFS4ERR_NOFILEHANDLE 6007 NFS4ERR_NOTDIR 6008 NFS4ERR_RESOURCE 6009 NFS4ERR_SERVERFAULT 6010 NFS4ERR_STALE 6011 NFS4ERR_SYMLINK 6012 NFS4ERR_WRONGSEC 6014 Draft Specification NFS version 4 Protocol January 2000 6016 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory 6018 SYNOPSIS 6020 (cfh) -> (cfh) 6022 ARGUMENT 6024 /* CURRENT_FH: object */ 6025 void; 6027 RESULT 6029 struct LOOKUPP4res { 6030 /* CURRENT_FH: directory */ 6031 nfsstat4 status; 6032 }; 6034 DESCRIPTION 6036 The current filehandle is assumed to refer to a regular directory 6037 or a named attribute directory. LOOKUPP assigns the filehandle for 6038 its parent directory to be the current filehandle. If there is no 6039 parent directory an NFS4ERR_ENOENT error must be returned. 6040 Therefore, NFS4ERR_ENOENT will be returned by the server when the 6041 current filehandle is at the root or top of the server's file tree. 6043 IMPLEMENTATION 6045 As for LOOKUP, LOOKUPP will also cross mountpoints. 6047 ERRORS 6049 NFS4ERR_ACCES 6050 NFS4ERR_BADHANDLE 6051 NFS4ERR_FHEXPIRED 6052 NFS4ERR_INVAL 6053 NFS4ERR_IO 6054 NFS4ERR_MOVED 6055 NFS4ERR_NOENT 6056 NFS4ERR_NOFILEHANDLE 6057 NFS4ERR_RESOURCE 6058 NFS4ERR_SERVERFAULT 6059 NFS4ERR_STALE 6061 Draft Specification NFS version 4 Protocol January 2000 6063 NFS4ERR_WRONGSEC 6065 Draft Specification NFS version 4 Protocol January 2000 6067 14.2.15. Operation 17: NVERIFY - Verify Difference in Attributes 6069 SYNOPSIS 6071 (cfh), attrbits, attrvals -> - 6073 ARGUMENT 6075 struct NVERIFY4args { 6076 /* CURRENT_FH: object */ 6077 bitmap4 attr_request; 6078 fattr4 obj_attributes; 6079 }; 6081 RESULT 6083 struct NVERIFY4res { 6084 nfsstat4 status; 6085 }; 6087 DESCRIPTION 6089 This operation is used to prefix a sequence of operations to be 6090 performed if one or more attributes have changed on some filesystem 6091 object. If all the attributes match then the error NFS4ERR_SAME 6092 must be returned. 6094 IMPLEMENTATION 6096 This operation is useful as a cache validation operator. If the 6097 object to which the attributes belong has changed then the 6098 following operations may obtain new data associated with that 6099 object. For instance, to check if a file has been changed and 6100 obtain new data if it has: 6102 PUTFH (public) 6103 LOOKUP "pub" "foo" "bar" 6104 NVERIFY attrbits attrs 6105 READ 0 32767 6107 ERRORS 6109 Draft Specification NFS version 4 Protocol January 2000 6111 NFS4ERR_ACCES 6112 NFS4ERR_BADHANDLE 6113 NFS4ERR_DELAY 6114 NFS4ERR_FHEXPIRED 6115 NFS4ERR_INVAL 6116 NFS4ERR_IO 6117 NFS4ERR_MOVED 6118 NFS4ERR_NOFILEHANDLE 6119 NFS4ERR_RESOURCE 6120 NFS4ERR_SAME 6121 NFS4ERR_SERVERFAULT 6122 NFS4ERR_STALE 6123 NFS4ERR_WRONGSEC 6125 Draft Specification NFS version 4 Protocol January 2000 6127 14.2.16. Operation 18: OPEN - Open a Regular File 6129 SYNOPSIS 6131 (cfh), claim, openhow, owner, seqid, access, deny -> (cfh), 6132 stateid, cinfo, rflags, open_confirm, delegation 6134 ARGUMENT 6136 struct OPEN4args { 6137 open_claim4 claim; 6138 openflag4 openhow; 6139 nfs_lockowner4 owner; 6140 seqid4 seqid; 6141 uint32_t share_access; 6142 uint32_t share_deny; 6143 }; 6145 enum createmode4 { 6146 UNCHECKED4 = 0, 6147 GUARDED4 = 1, 6148 EXCLUSIVE4 = 2 6149 }; 6151 union createhow4 switch (createmode4 mode) { 6152 case UNCHECKED4: 6153 case GUARDED4: 6154 fattr4 createattrs; 6155 case EXCLUSIVE4: 6156 verifier4 createverf; 6157 }; 6159 enum opentype4 { 6160 OPEN4_NOCREATE = 0, 6161 OPEN4_CREATE = 1 6162 }; 6164 union openflag4 switch (opentype4 opentype) { 6165 case OPEN4_CREATE: 6166 createhow4 how; 6167 default: 6168 void; 6169 }; 6171 /* Next definitions used for OPEN delegation */ 6172 enum limit_by4 { 6173 NFS_LIMIT_SIZE = 1, 6175 Draft Specification NFS version 4 Protocol January 2000 6177 NFS_LIMIT_BLOCKS = 2 6178 /* others as needed */ 6179 }; 6181 struct nfs_modified_limit4 { 6182 uint32_t num_blocks; 6183 uint32_t bytes_per_block; 6184 }; 6186 union nfs_space_limit4 switch (limit_by4 limitby) { 6187 /* limit specified as file size */ 6188 case NFS_LIMIT_SIZE: 6189 uint64_t filesize; 6190 /* limit specified by number of blocks */ 6191 case NFS_LIMIT_BLOCKS: 6192 nfs_modified_limit4 mod_blocks; 6193 } ; 6195 enum open_delegation_type4 { 6196 OPEN_DELEGATE_NONE = 0, 6197 OPEN_DELEGATE_READ = 1, 6198 OPEN_DELEGATE_WRITE = 2 6199 }; 6201 enum open_claim_type4 { 6202 CLAIM_NULL = 0, 6203 CLAIM_PREVIOUS = 1, 6204 CLAIM_DELEGATE_CUR = 2, 6205 CLAIM_DELEGATE_PREV = 3 6206 }; 6208 struct open_claim_delegate_cur4 { 6209 pathname4 file; 6210 stateid4 delegate_stateid; 6211 }; 6213 union open_claim4 switch (open_claim_type4 claim) { 6214 /* 6215 * No special rights to file. Ordinary OPEN of the specified file. 6216 */ 6217 case CLAIM_NULL: 6218 /* CURRENT_FH: directory */ 6219 pathname4 file; 6221 /* 6222 * Right to the file established by an open previous to server 6223 * reboot. File identified by filehandle obtained at that time 6224 * rather than by name. 6226 Draft Specification NFS version 4 Protocol January 2000 6228 */ 6229 case CLAIM_PREVIOUS: 6230 /* CURRENT_FH: file being reclaimed */ 6231 uint32_t delegate_type; 6233 /* 6234 * Right to file based on a delegation granted by the server. 6235 * File is specified by name. 6236 */ 6237 case CLAIM_DELEGATE_CUR: 6238 /* CURRENT_FH: directory */ 6239 open_claim_delegate_cur4 delegate_cur_info; 6241 /* Right to file based on a delegation granted to a previous boot 6242 * instance of the client. File is specified by name. 6243 */ 6244 case CLAIM_DELEGATE_PREV: 6245 /* CURRENT_FH: directory */ 6246 pathname4 file_delegate_prev; 6247 }; 6249 RESULT 6251 struct open_read_delegation4 { 6252 stateid4 stateid; /* Stateid for delegation*/ 6253 bool recall; /* Pre-recalled flag for 6254 delegations obtained 6255 by reclaim 6256 (CLAIM_PREVIOUS) */ 6257 nfsace4 permissions; /* Defines users who don't 6258 need an ACCESS call to 6259 open for read */ 6260 }; 6262 struct open_write_delegation4 { 6263 stateid4 stateid; /* Stateid for delegation 6264 be flushed to the server 6265 on close. */ 6266 bool recall; /* Pre-recalled flag for 6267 delegations obtained 6268 by reclaim 6269 (CLAIM_PREVIOUS) */ 6270 nfs_space_limit4 space_limit; /* Defines condition that 6271 the client must check to 6272 determine whether the 6273 file needs to be flushed 6275 Draft Specification NFS version 4 Protocol January 2000 6277 to the server on close. 6278 */ 6279 nfsace4 permissions; /* Defines users who don't 6280 need an ACCESS call as 6281 part of a delegated 6282 open. */ 6283 }; 6285 union open_delegation4 6286 switch (open_delegation_type4 delegation_type) { 6287 case OPEN_DELEGATE_NONE: 6288 void; 6289 case OPEN_DELEGATE_READ: 6290 open_read_delegation4 read; 6291 case OPEN_DELEGATE_WRITE: 6292 open_write_delegation4 write; 6293 }; 6295 const OPEN4_RESULT_MLOCK = 0x00000001; 6296 const OPEN4_RESULT_CONFIRM= 0x00000002; 6298 struct OPEN4resok { 6299 stateid4 stateid; /* Stateid for open */ 6300 change_info4 cinfo; /* Directory Change Info */ 6301 uint32_t rflags; /* Result flags */ 6302 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 6303 open_delegation4 delegation; /* Info on any open 6304 delegation */ 6305 }; 6307 union OPEN4res switch (nfsstat4 status) { 6308 case NFS4_OK: 6309 /* CURRENT_FH: opened file */ 6310 OPEN4resok result; 6311 default: 6312 void; 6313 }; 6315 DESCRIPTION 6317 The OPEN operation creates and/or opens a regular file in a 6318 directory with the provided name. If the file does not exist at 6319 the server and creation is desired, specification of the method of 6320 creation is provided by the openhow parameter. The client has the 6321 choice of three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE. 6323 UNCHECKED means that the file should be created if a file of that 6325 Draft Specification NFS version 4 Protocol January 2000 6327 name does not exist and encountering an existing regular file of 6328 that name is not an error. For this type of create, createattrs 6329 specifies the initial set of attributes for the file. The set of 6330 attributes may includes any writable attribute valid for regular 6331 files. When an UNCHECKED create encounters an existing file, the 6332 attributes specified by createattrs is not used, except that when 6333 an object_size of zero is specified, the existing file is 6334 truncated. If GUARDED is specified, the server checks for the 6335 presence of a duplicate object by name before performing the 6336 create. If a duplicate exists, an error of NFS4ERR_EXIST is 6337 returned as the status. If the object does not exist, the request 6338 is performed as described for UNCHECKED. 6340 EXCLUSIVE specifies that the server is to follow exclusive creation 6341 semantics, using the verifier to ensure exclusive creation of the 6342 target. The server should check for the presence of a duplicate 6343 object by name. If the object does not exist, the server creates 6344 the object and stores the verifier with the object. If the object 6345 does exist and the stored verifier matches the client provided 6346 verifier, the server uses the existing object as the newly created 6347 object. If the stored verifier does not match, then an error of 6348 NFS4ERR_EXIST is returned. No attributes may be provided in this 6349 case, since the server may use an attribute of the target object to 6350 store the verifier. 6352 For the target directory, the server returns change_info4 6353 information in cinfo. With the atomic field of the change_info4 6354 struct, the server will indicate if the before and after change 6355 attributes were obtained atomically with respect to the link 6356 creation. 6358 Upon successful creation, the current filehandle is replaced by 6359 that of the new object. 6361 The OPEN procedure provides for DOS SHARE capability with the use 6362 of the access and deny fields of the OPEN arguments. The client 6363 specifies at OPEN the required access and deny modes. For clients 6364 that do not directly support SHAREs (i.e. Unix), the expected deny 6365 value is DENY_NONE. In the case that there is a existing SHARE 6366 reservation that conflicts with the OPEN request, the server 6367 returns the error NFS4ERR_DENIED. For a complete SHARE request, 6368 the client must provide values for the owner and seqid fields for 6369 the OPEN argument. For additional discussion of SHARE semantics 6370 see the section on 'Share Reservations'. 6372 In the case that the client is recovering state from a server 6373 failure, the reclaim field of the OPEN argument is used to signify 6374 that the request is meant to reclaim state previously held. 6376 Draft Specification NFS version 4 Protocol January 2000 6378 The "claim" field of the OPEN argument is used to specify the file 6379 to be opened and the state information which the client claims to 6380 possess. There are four basic claim types which cover the various 6381 situations for an OPEN. They are as follows: 6383 CLAIM_NULL 6384 For the client, this is a new OPEN 6385 request and there is no previous state 6386 associate with the file for the client. 6388 CLAIM_PREVIOUS 6389 The client is claiming basic OPEN state 6390 for a file that was held previous to a 6391 server reboot. Generally used when a 6392 server is returning persistent file 6393 handles; the client may not have the 6394 file name to reclaim the OPEN. 6396 CLAIM_DELEGATE_CUR 6397 The client is claiming a delegation for 6398 OPEN as granted by the server. 6399 Generally this is done as part of 6400 recalling a delegation. 6402 CLAIM_DELEGATE_PREV 6403 The client is claiming a delegation 6404 granted to a previous client instance; 6405 used after the client reboots. 6407 For OPEN requests whose claim type is other than CLAIM_PREVIOUS 6408 (i.e. requests other than those devoted to reclaiming opens after a 6409 server reboot) that reach the server during its grace or lease 6410 expiration period, the server returns an error of NFS4ERR_GRACE. 6412 For any OPEN request, the server may return an open delegation, 6413 which allows further opens and closes to be handled locally on the 6414 client as described in the section Open Delegation. Note that 6415 delegation is up to the server to decide. The client should never 6416 assume that delegation will or will not be granted in a particular 6417 instance. It should always be prepared for either case. A partial 6418 exception is the reclaim (CLAIM_PREVIOUS) case, in which a 6419 delegation type is claimed. In this case, delegation will always 6420 be granted, although the server may specify an immediate recall in 6421 the delegation structure. 6423 The rflags returned by a successful OPEN allow the server to return 6424 information governing how the open file is to be handled. 6425 OPEN4_RESULT_MLOCK indicates to the caller that mandatory locking 6426 is in effect for this file and the client should act appropriately 6427 with regard to data cached on the client. OPEN4_RESULT_CONFIRM 6428 indicates that the client MUST execute an OPEN_CONFIRM operation 6430 Draft Specification NFS version 4 Protocol January 2000 6432 before using the open file. 6434 If the file is a zero length array, if any component does not obey 6435 the UTF-8 definition, or if any component in the path is of zero 6436 length, the error NFS4ERR_INVAL will be returned. 6438 When an OPEN is done and the specified lockowner already has the 6439 resulting filehandle open, the result is to "OR" together the new 6440 share and deny status together with the existing status. In this 6441 case, only a single CLOSE need be done, even though multiple OPEN's 6442 were completed. 6444 IMPLEMENTATION 6446 The OPEN procedure contains support for EXCLUSIVE create. The 6447 mechanism is similar to the support in NFS version 3 [RFC1813]. As 6448 in NFS version 3, this mechanism provides reliable exclusive 6449 creation. Exclusive create is invoked when the how parameter is 6450 EXCLUSIVE. In this case, the client provides a verifier that can 6451 reasonably be expected to be unique. A combination of a client 6452 identifier, perhaps the client network address, and a unique number 6453 generated by the client, perhaps the RPC transaction identifier, 6454 may be appropriate. 6456 If the object does not exist, the server creates the object and 6457 stores the verifier in stable storage. For file systems that do not 6458 provide a mechanism for the storage of arbitrary file attributes, 6459 the server may use one or more elements of the object meta-data to 6460 store the verifier. The verifier must be stored in stable storage 6461 to prevent erroneous failure on retransmission of the request. It 6462 is assumed that an exclusive create is being performed because 6463 exclusive semantics are critical to the application. Because of the 6464 expected usage, exclusive CREATE does not rely solely on the 6465 normally volatile duplicate request cache for storage of the 6466 verifier. The duplicate request cache in volatile storage does not 6467 survive a crash and may actually flush on a long network partition, 6468 opening failure windows. In the UNIX local file system 6469 environment, the expected storage location for the verifier on 6470 creation is the meta-data (time stamps) of the object. For this 6471 reason, an exclusive object create may not include initial 6472 attributes because the server would have nowhere to store the 6473 verifier. 6475 If the server can not support these exclusive create semantics, 6476 possibly because of the requirement to commit the verifier to 6477 stable storage, it should fail the OPEN request with the error, 6478 NFS4ERR_NOTSUPP. 6480 Draft Specification NFS version 4 Protocol January 2000 6482 During an exclusive CREATE request, if the object already exists, 6483 the server reconstructs the object's verifier and compares it with 6484 the verifier in the request. If they match, the server treats the 6485 request as a success. The request is presumed to be a duplicate of 6486 an earlier, successful request for which the reply was lost and 6487 that the server duplicate request cache mechanism did not detect. 6488 If the verifiers do not match, the request is rejected with the 6489 status, NFS4ERR_EXIST. 6491 Once the client has performed a successful exclusive create, it 6492 must issue a SETATTR to set the correct object attributes. Until 6493 it does so, it should not rely upon any of the object attributes, 6494 since the server implementation may need to overload object meta- 6495 data to store the verifier. The subsequent SETATTR must not occur 6496 in the same COMPOUND request as the OPEN. This separation will 6497 guarantee that the exclusive create mechanism will continue to 6498 function properly in the face of retransmission of the request. 6500 Use of the GUARDED attribute does not provide exactly-once 6501 semantics. In particular, if a reply is lost and the server does 6502 not detect the retransmission of the request, the procedure can 6503 fail with NFS4ERR_EXIST, even though the create was performed 6504 successfully. 6506 For SHARE reservations, the client must specify a value for access 6507 that is one of READ, WRITE, or BOTH. For deny, the client must 6508 specify one of NONE, READ, WRITE, or BOTH. If the client fails to 6509 do this, the server must return NFS4ERR_INVAL. 6511 ERRORS 6513 NFS4ERR_ACCES 6514 NFS4ERR_BAD_SEQID 6515 NFS4ERR_DELAY 6516 NFS4ERR_DQUOT 6517 NFS4ERR_EXIST 6518 NFS4ERR_FHEXPIRED 6519 NFS4ERR_GRACE 6520 NFS4ERR_IO 6521 NFS4ERR_MOVED 6522 NFS4ERR_NAMETOOLONG 6523 NFS4ERR_NOFILEHANDLE 6524 NFS4ERR_NOSPC 6525 NFS4ERR_NOTDIR 6526 NFS4ERR_NOTSUPP 6527 NFS4ERR_RESOURCE 6528 NFS4ERR_ROFS 6530 Draft Specification NFS version 4 Protocol January 2000 6532 NFS4ERR_SERVERFAULT 6533 NFS4ERR_SHARE_DENIED 6534 NFS4ERR_STALE_CLIENTID 6536 Draft Specification NFS version 4 Protocol January 2000 6538 14.2.17. Operation 19: OPENATTR - Open Named Attribute Directory 6540 SYNOPSIS 6542 (cfh) -> (cfh) 6544 ARGUMENT 6546 /* CURRENT_FH: file or directory */ 6547 void; 6549 RESULT 6551 struct OPENATTR4res { 6552 /* CURRENT_FH: name attr directory*/ 6553 nfsstat4 status; 6554 }; 6556 DESCRIPTION 6558 The OPENATTR operation is used to obtain the filehandle of the 6559 named attribute directory associated with the current filehandle. 6560 The result of the OPENATTR will be a filehandle to an object of 6561 type NF4ATTRDIR. From this filehandle, READDIR and LOOKUP 6562 procedures can be used to obtain filehandles for the various named 6563 attributes associated with the original file system object. 6564 Filehandles returned within the named attribute directory will have 6565 a type of NF4NAMEDATTR. 6567 IMPLEMENTATION 6569 If the server does not support named attributes for the current 6570 filehandle, an error of NFS4ERR_NOTSUPP will be returned to the 6571 client. 6573 ERRORS 6575 NFS4ERR_ACCES 6576 NFS4ERR_BADHANDLE 6577 NFS4ERR_DELAY 6578 NFS4ERR_FHEXPIRED 6579 NFS4ERR_INVAL 6580 NFS4ERR_IO 6582 Draft Specification NFS version 4 Protocol January 2000 6584 NFS4ERR_MOVED 6585 NFS4ERR_NOENT 6586 NFS4ERR_NOFILEHANDLE 6587 NFS4ERR_NOTSUPP 6588 NFS4ERR_RESOURCE 6589 NFS4ERR_SERVERFAULT 6590 NFS4ERR_STALE 6591 NFS4ERR_WRONGSEC 6593 Draft Specification NFS version 4 Protocol January 2000 6595 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open 6597 SYNOPSIS 6599 (cfh), seqid, open_confirm-> stateid 6601 ARGUMENT 6603 struct OPEN_CONFIRM4args { 6604 /* CURRENT_FH: opened file */ 6605 seqid4 seqid; 6606 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 6607 }; 6609 RESULT 6611 struct OPEN_CONFIRM4resok { 6612 stateid4 stateid; 6613 }; 6615 union OPEN_CONFIRM4res switch (nfsstat4 status) { 6616 case NFS4_OK: 6617 OPEN_CONFIRM4resok resok4; 6618 default: 6619 void; 6620 }; 6622 DESCRIPTION 6624 This operation is used to confirm the sequence id usage for the 6625 first time that a nfs_lockowner is used by a client. The OPEN 6626 operation returns a opaque confirmation verifier that is then 6627 passed to this operation along with the next sequence id for the 6628 nfs_lockowner. The sequence id passed to the OPEN_CONFIRM must be 6629 1 (one) greater than the seqid passed to the OPEN operation from 6630 which the open_confirm value was obtained. If the server receives 6631 an unexpected sequence id with respect to the original open, then 6632 the server assumes that the client will not confirm the original 6633 OPEN and all state associated with the original OPEN is released by 6634 the server. 6636 On success, the current filehandle retains its value. 6638 IMPLEMENTATION 6640 Draft Specification NFS version 4 Protocol January 2000 6642 A given client might generate many nfs_lockowner data structures 6643 for a given clientid. The client will periodically either dispose 6644 of its nfs_lockowners or stop using them for indefinite periods of 6645 time. The latter situation is why the NFS version 4 protocol does 6646 not have a an explicit operation to exit an nfs_lockowner: such an 6647 operation is of no use in that situation. Instead, to avoid 6648 unbounded memory use, the server needs to implement a strategy for 6649 disposing of nfs_lockowners that have no current lock, open, or 6650 delegation state for any files and have not been used recently. 6651 The time period used to determine when to dispose of nfs_lockowners 6652 is an implementation choice. The time period should certainly be 6653 no less than the lease time plus any grace period the server wishes 6654 to implement beyond a lease time. The OPEN_CONFIRM operation 6655 allows the server to safely dispose of unused nfs_lockowner data 6656 structures. 6658 In the case that a client issues an OPEN operation and the server 6659 no longer has a record of the nfs_lockowner, the server needs 6660 ensure that this is a new OPEN and not a replay or retransmission. 6662 A lazy server implementation might require confirmation for every 6663 nfs_lockowner for which it has no record. However, this is not 6664 necessary until the server records the fact that it has disposed of 6665 one nfs_lockowner for the given clientid. 6667 The server must hold unconfirmed OPEN state until one of three 6668 events occur. First, the client sends an OPEN_CONFIRM request with 6669 the appropriate sequence id and confirmation verifier within the 6670 lease period. In this case, the OPEN state on the server goes to 6671 confirmed, and the nfs_lockowner on the server is fully 6672 established. 6674 Second, the client sends another OPEN request with a sequence id 6675 that is incorrect for the nfs_lockowner (out of sequence). In this 6676 case, the server assumes the second OPEN request is valid and the 6677 first one is a replay. The server cancels the OPEN state of the 6678 first OPEN requests, establishes an unconfirmed OPEN state for the 6679 second OPEN request, and responds to the second OPEN request with 6680 an indication that an OPEN_CONFIRM is needed. The process then 6681 repeats itself. While there is a potential for a denial of service 6682 attack on the client, it is mitigated if the client and server 6683 require the use of a security flavor based on Kerberos V5, LIPKEY, 6684 or some other flavor that uses cryptography. 6686 What if the server is in the unconfirmed OPEN state for a given 6687 nfs_lockowner, and it receives an operation on the nfs_lockowner 6688 that has a stateid but the operation is not OPEN, or it is 6689 OPEN_CONFIRM but with the wrong confirmation verifier? Then, even 6691 Draft Specification NFS version 4 Protocol January 2000 6693 if the seqid is correct, the server returns NFS4ERR_BAD_STATEID, 6694 because the server assumes the operation is a replay: if the server 6695 has no established OPEN state, then there is no way, for example, a 6696 LOCK operation could be valid. 6698 Third, neither of the two aforementioned events occur for the 6699 nfs_lockowner within the lease period. In this case, the OPEN 6700 state is cancelled and disposal of the nfs_lockowner can occur. 6702 ERRORS 6704 NFS4ERR_BADHANDLE 6705 NFS4ERR_BAD_SEQID 6706 NFS4ERR_EXPIRED 6707 NFS4ERR_FHEXPIRED 6708 NFS4ERR_GRACE 6709 NFS4ERR_INVAL 6710 NFS4ERR_MOVED 6711 NFS4ERR_NOENT 6712 NFS4ERR_NOFILEHANDLE 6713 NFS4ERR_NOTSUPP 6714 NFS4ERR_RESOURCE 6715 NFS4ERR_SERVERFAULT 6716 NFS4ERR_STALE 6717 NFS4ERR_WRONGSEC 6719 Draft Specification NFS version 4 Protocol January 2000 6721 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access 6723 SYNOPSIS 6725 (cfh), stateid, seqid, access, deny -> stateid 6727 ARGUMENT 6729 struct OPEN_DOWNGRADE4args { 6730 /* CURRENT_FH: opened file */ 6731 stateid4 stateid; 6732 seqid4 seqid; 6733 uint32_t share_access; 6734 uint32_t share_deny; 6735 }; 6737 RESULT 6739 struct OPEN_DOWNGRADE4resok { 6740 stateid4 stateid; 6741 }; 6743 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 6744 case NFS4_OK: 6745 OPEN_DOWNGRADE4resok resok4; 6746 default: 6747 void; 6748 }; 6750 This operation is used to adjust the access and deny bits for a given 6751 open. This is necessary when a given lockowner opens the same file 6752 multiple times with different access and deny flags. In this 6753 situation, a close of one of the open's may change the appropriate 6754 access and deny flags to remove bits associated with open's no longer 6755 in effect. 6757 The access and deny bits speicifed in this operation replace the 6758 current ones for the specified open file. If either the access or 6759 the deny mode specified includes bits not in effect for the open, the 6760 error NFS4ERR_INVAL should be returned. Since access and deny bits 6761 are subsets of those already granted, it is is not possible for this 6762 request to denied because of conflicting share reservations. 6764 On success, the current filehandle retains its value. 6766 Draft Specification NFS version 4 Protocol January 2000 6768 ERRORS 6770 NFS4ERR_BADHANDLE 6771 NFS4ERR_BAD_SEQID 6772 NFS4ERR_BAD_STATEID 6773 NFS4ERR_EXPIRED 6774 NFS4ERR_FHEXPIRED 6775 NFS4ERR_INVAL 6776 NFS4ERR_MOVED 6777 NFS4ERR_NOFILEHANDLE 6778 NFS4ERR_OLD_STATEID 6779 NFS4ERR_RESOURCE 6780 NFS4ERR_SERVERFAULT 6781 NFS4ERR_STALE 6782 NFS4ERR_STALE_STATEID 6784 Draft Specification NFS version 4 Protocol January 2000 6786 14.2.20. Operation 22: PUTFH - Set Current Filehandle 6788 SYNOPSIS 6790 filehandle -> (cfh) 6792 ARGUMENT 6794 struct PUTFH4args { 6795 nfs4_fh object; 6796 }; 6798 RESULT 6800 struct PUTFH4res { 6801 /* CURRENT_FH: */ 6802 nfsstat4 status; 6803 }; 6805 DESCRIPTION 6807 Replaces the current filehandle with the filehandle provided as an 6808 argument. 6810 IMPLEMENTATION 6812 Commonly used as the first operator in an NFS request to set the 6813 context for following operations. 6815 ERRORS 6817 NFS4ERR_BADHANDLE 6818 NFS4ERR_FHEXPIRED 6819 NFS4ERR_MOVED 6820 NFS4ERR_RESOURCE 6821 NFS4ERR_SERVERFAULT 6822 NFS4ERR_STALE 6823 NFS4ERR_WRONGSEC 6825 Draft Specification NFS version 4 Protocol January 2000 6827 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle 6829 SYNOPSIS 6831 - -> (cfh) 6833 ARGUMENT 6835 void; 6837 RESULT 6839 struct PUTPUBFH4res { 6840 /* CURRENT_FH: root fh */ 6841 nfsstat4 status; 6842 }; 6844 DESCRIPTION 6846 Replaces the current filehandle with the filehandle that represents 6847 the public filehandle of the server's name space. This filehandle 6848 may be different from the "root" filehandle which may be associated 6849 with some other directory on the server. 6851 IMPLEMENTATION 6853 Used as the first operator in an NFS request to set the context for 6854 following operations. 6856 ERRORS 6858 NFS4ERR_RESOURCE 6859 NFS4ERR_SERVERFAULT 6860 NFS4ERR_WRONGSEC 6862 Draft Specification NFS version 4 Protocol January 2000 6864 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle 6866 SYNOPSIS 6868 - -> (cfh) 6870 ARGUMENT 6872 void; 6874 RESULT 6876 struct PUTROOTFH4res { 6877 /* CURRENT_FH: root fh */ 6878 nfsstat4 status; 6879 }; 6881 DESCRIPTION 6883 Replaces the current filehandle with the filehandle that represents 6884 the root of the server's name space. From this filehandle a LOOKUP 6885 operation can locate any other filehandle on the server. This 6886 filehandle may be different from the "public" filehandle which may 6887 be associated with some other directory on the server. 6889 IMPLEMENTATION 6891 Commonly used as the first operator in an NFS request to set the 6892 context for following operations. 6894 ERRORS 6896 NFS4ERR_RESOURCE 6897 NFS4ERR_SERVERFAULT 6898 NFS4ERR_WRONGSEC 6900 Draft Specification NFS version 4 Protocol January 2000 6902 14.2.23. Operation 25: READ - Read from File 6904 SYNOPSIS 6906 (cfh), offset, count, stateid -> eof, data 6908 ARGUMENT 6910 struct READ4args { 6911 /* CURRENT_FH: file */ 6912 stateid4 stateid; 6913 offset4 offset; 6914 count4 count; 6915 }; 6917 RESULT 6919 struct READ4resok { 6920 bool eof; 6921 opaque data<>; 6922 }; 6924 union READ4res switch (nfsstat4 status) { 6925 case NFS4_OK: 6926 READ4resok resok4; 6927 default: 6928 void; 6929 }; 6931 DESCRIPTION 6933 The READ operation reads data from the regular file identified by 6934 the current filehandle. 6936 The client provides an offset of where the READ is to start and a 6937 count of how many bytes are to be read. An offset of 0 (zero) 6938 means to read data starting at the beginning of the file. If 6939 offset is greater than or equal to the size of the file, the 6940 status, NFS4_OK, is returned with a data length set to 0 (zero) and 6941 eof set to TRUE. The READ is subject to access permissions 6942 checking. 6944 If the client specifies a count value of 0 (zero), the READ 6945 succeeds and returns 0 (zero) bytes of data again subject to access 6946 permissions checking. The server may choose to return fewer bytes 6948 Draft Specification NFS version 4 Protocol January 2000 6950 than specified by the client. The client needs to check for this 6951 condition and handle the condition appropriately. 6953 The stateid value for a READ request represents a value returned 6954 from a previous record lock or share reservation request. Used by 6955 the server to verify that the associated lock is still valid and to 6956 update lease timeouts for the client. 6958 If the read ended at the end-of-file (formally, in a correctly 6959 formed READ request, if offset + count is equal to the size of the 6960 file), eof is returned as TRUE; otherwise it is FALSE. A successful 6961 READ of an empty file will always return eof as TRUE. 6963 IMPLEMENTATION 6965 It is possible for the server to return fewer than count bytes of 6966 data. If the server returns less than the count requested and eof 6967 set to FALSE, the client should issue another READ to get the 6968 remaining data. A server may return less data than requested under 6969 several circumstances. The file may have been truncated by another 6970 client or perhaps on the server itself, changing the file size from 6971 what the requesting client believes to be the case. This would 6972 reduce the actual amount of data available to the client. It is 6973 possible that the server may back off the transfer size and reduce 6974 the read request return. Server resource exhaustion may also occur 6975 necessitating a smaller read return. 6977 If the file is locked the server will return an NFS4ERR_LOCKED 6978 error. Since the lock may be of short duration, the client may 6979 choose to retransmit the READ request (with exponential backoff) 6980 until the operation succeeds. 6982 ERRORS 6984 NFS4ERR_ACCES 6985 NFS4ERR_BADHANDLE 6986 NFS4ERR_BAD_STATEID 6987 NFS4ERR_DELAY 6988 NFS4ERR_DENIED 6989 NFS4ERR_EXPIRED 6990 NFS4ERR_FHEXPIRED 6991 NFS4ERR_GRACE 6992 NFS4ERR_INVAL 6993 NFS4ERR_IO 6994 NFS4ERR_LOCKED 6995 NFS4ERR_MOVED 6997 Draft Specification NFS version 4 Protocol January 2000 6999 NFS4ERR_NOFILEHANDLE 7000 NFS4ERR_NXIO 7001 NFS4ERR_OLD_STATEID 7002 NFS4ERR_RESOURCE 7003 NFS4ERR_SERVERFAULT 7004 NFS4ERR_STALE 7005 NFS4ERR_STALE_STATEID 7006 NFS4ERR_WRONGSEC 7008 Draft Specification NFS version 4 Protocol January 2000 7010 14.2.24. Operation 26: READDIR - Read Directory 7012 SYNOPSIS 7013 (cfh), cookie, cookieverf, dircount, maxcount, attrbits -> 7014 cookieverf { cookie, filename, attrbits, attributes } 7016 ARGUMENT 7018 struct READDIR4args { 7019 /* CURRENT_FH: directory */ 7020 nfs_cookie4 cookie; 7021 verifier4 cookieverf; 7022 count4 dircount; 7023 count4 maxcount; 7024 bitmap4 attr_request; 7025 }; 7027 RESULT 7029 struct entry4 { 7030 nfs_cookie4 cookie; 7031 component4 name; 7032 fattr4 attrs; 7033 entry4 *nextentry; 7034 }; 7036 struct dirlist4 { 7037 entry4 *entries; 7038 bool eof; 7039 }; 7041 struct READDIR4resok { 7042 verifier4 cookieverf; 7043 dirlist4 reply; 7044 }; 7046 union READDIR4res switch (nfsstat4 status) { 7047 case NFS4_OK: 7048 READDIR4resok resok4; 7049 default: 7050 void; 7051 }; 7053 DESCRIPTION 7055 Draft Specification NFS version 4 Protocol January 2000 7057 The READDIR operation retrieves a variable number of entries from a 7058 file system directory and returns client requested attributes for 7059 each entry along with information to allow the client to request 7060 additional directory entries in a subsequent READDIR. 7062 The arguments contain a cookie value that represents where the 7063 READDIR should start within the directory. A value of 0 (zero) for 7064 the cookie is used to start reading at the beginning of the 7065 directory. For subsequent READDIR requests, the client specifies a 7066 cookie value that is provided by the server on a previous READDIR 7067 request. 7069 The cookieverf value should be set to 0 (zero) when the cookie 7070 value is 0 (zero) (first directory read). On subsequent requests, 7071 it should be a cookieverf as returned by the server. The 7072 cookieverf must match that returned by the READDIR in which the 7073 cookie was acquired. 7075 The dircount portion of the argument is a hint of the maximum 7076 number of bytes of directory information that should be returned. 7077 This value is the XDR encoded length of the name of the directory 7078 entries and the cookie value for the entries. The server may 7079 return less data. 7081 The maxcount value of the argument is the maximum number of bytes 7082 for the result. This maximum size represents all of the data being 7083 returned and includes the XDR overhead. The server may return less 7084 data. If the server is unable to return a single directory entry 7085 within the maxcount limit, the error NFS4ERR_READDIR_NOSPC will be 7086 returned to the client. 7088 Finally, attrbits represents the list of attributes to be returned 7089 for each directory entry supplied by the server. 7091 On successful return, the server's response will provide a list of 7092 directory entries. Each of these entries contains the name of the 7093 directory entry, a cookie value for that entry, and the associated 7094 attributes as requested. 7096 The cookie value is only meaningful to the server and is used as a 7097 "bookmark" for the directory entry. As mentioned, this cookie is 7098 used by the client for subsequent READDIR operations so that it may 7099 continue reading a directory. The cookie is similar in concept to 7100 a READ offset but should not be interpreted as such by the client. 7101 Ideally, the cookie value should not change if the directory is 7102 modified. 7104 In some cases, the server may encounter an error while obtaining 7106 Draft Specification NFS version 4 Protocol January 2000 7108 the attributes for a directory entry. Instead of returning an 7109 error for the entire READDIR operation, the server can instead 7110 return the attribute 'fattr4_rdattr_error'. With this, the server 7111 is able to communicate the failure to the client and not fail the 7112 entire operation in the instance of what might be a transient 7113 failure. Obviously, the client must request the 7114 fattr4_rdattr_error attribute for this method to work properly. If 7115 the client does not request the attribute, the server has no choice 7116 but to return failure for the entire READDIR operation. 7118 For some file system environments, the directory entries "." and 7119 ".." have special meaning and in other environments, they may not. 7120 If the server supports these special entries within a directory, 7121 they should not be returned to the client as part of the READDIR 7122 response. To enable some client environments, the cookie values of 7123 0, 1, and 2 are to be considered reserved. For READDIR arguments, 7124 cookie values of 1 and 2 should not be used and for READDIR results 7125 cookie values of 0, 1, and 2 should not returned. 7127 IMPLEMENTATION 7129 The server's file system directory representations can differ 7130 greatly. A client's programming interfaces may also be bound to 7131 the local operating environment in a way that does not translate 7132 well into the NFS protocol. Therefore the use of the dircount and 7133 maxcount fields are provided to allow the client the ability to 7134 provide guidelines to the server. If the client is aggressive 7135 about attribute collection during a READDIR, the server has an idea 7136 of how to limit the encoded response. The dircount field provides 7137 a hint on the number of entries based solely on the names of the 7138 directory entries. 7140 The cookieverf may be used by the server to help manage cookie 7141 values that may become stale. It should be a rare occurrence that 7142 a server is unable to continue properly reading a directory with 7143 the provided cookie/cookieverf pair. The server should make every 7144 effort to avoid this condition since the application at the client 7145 may not be able to properly handle this type of failure. 7147 The use of the cookieverf will also protect the client from using 7148 READDIR cookie values that may be stale. For example, if the file 7149 system has been migrated, the server may or may not be able to use 7150 the same cookie values to service READDIR as the previous server 7151 used. With the client providing the cookieverf, the server is able 7152 to provide the appropriate response to the client. This prevents 7153 the case where the server may accept a cookie value but the 7154 underlying directory has changed and the response is invalid from 7156 Draft Specification NFS version 4 Protocol January 2000 7158 the client's context of its previous READDIR. 7160 Since the server will not be returning "." and ".." entries as has 7161 been done with previous versions of the NFS protocol, the client 7162 that requires these entries be present in READDIR responses must 7163 fabricate them. 7165 ERRORS 7167 NFS4ERR_ACCES 7168 NFS4ERR_BADHANDLE 7169 NFS4ERR_BAD_COOKIE 7170 NFS4ERR_DELAY 7171 NFS4ERR_FHEXPIRED 7172 NFS4ERR_INVAL 7173 NFS4ERR_IO 7174 NFS4ERR_MOVED 7175 NFS4ERR_NOFILEHANDLE 7176 NFS4ERR_NOTDIR 7177 NFS4ERR_NOTSUPP 7178 NFS4ERR_READDIR_NOSPC 7179 NFS4ERR_RESOURCE 7180 NFS4ERR_SERVERFAULT 7181 NFS4ERR_STALE 7182 NFS4ERR_TOOSMALL 7183 NFS4ERR_WRONGSEC 7185 Draft Specification NFS version 4 Protocol January 2000 7187 14.2.25. Operation 27: READLINK - Read Symbolic Link 7189 SYNOPSIS 7191 (cfh) -> linktext 7193 ARGUMENT 7195 /* CURRENT_FH: symlink */ 7196 void; 7198 RESULT 7200 struct READLINK4resok { 7201 linktext4 link; 7202 }; 7204 union READLINK4res switch (nfsstat4 status) { 7205 case NFS4_OK: 7206 READLINK4resok resok4; 7207 default: 7208 void; 7209 }; 7211 DESCRIPTION 7213 READLINK reads the data associated with a symbolic link. The data 7214 is a UTF-8 string that is opaque to the server. That is, whether 7215 created by an NFS client or created locally on the server, the data 7216 in a symbolic link is not interpreted when created, but is simply 7217 stored. 7219 IMPLEMENTATION 7221 A symbolic link is nominally a pointer to another file. The data 7222 is not necessarily interpreted by the server, just stored in the 7223 file. It is possible for a client implementation to store a path 7224 name that is not meaningful to the server operating system in a 7225 symbolic link. A READLINK operation returns the data to the client 7226 for interpretation. If different implementations want to share 7227 access to symbolic links, then they must agree on the 7228 interpretation of the data in the symbolic link. 7230 The READLINK operation is only allowed on objects of type, NF4LNK. 7232 Draft Specification NFS version 4 Protocol January 2000 7234 The server should return the error, NFS4ERR_INVAL, if the object is 7235 not of type, NF4LNK. 7237 ERRORS 7239 NFS4ERR_ACCES 7240 NFS4ERR_BADHANDLE 7241 NFS4ERR_DELAY 7242 NFS4ERR_FHEXPIRED 7243 NFS4ERR_INVAL 7244 NFS4ERR_IO 7245 NFS4ERR_MOVED 7246 NFS4ERR_NOFILEHANDLE 7247 NFS4ERR_NOTSUPP 7248 NFS4ERR_RESOURCE 7249 NFS4ERR_SERVERFAULT 7250 NFS4ERR_STALE 7251 NFS4ERR_WRONGSEC 7253 Draft Specification NFS version 4 Protocol January 2000 7255 14.2.26. Operation 28: REMOVE - Remove Filesystem Object 7257 SYNOPSIS 7259 (cfh), filename -> change_info 7261 ARGUMENT 7263 struct REMOVE4args { 7264 /* CURRENT_FH: directory */ 7265 component4 target; 7266 }; 7268 RESULT 7270 struct REMOVE4resok { 7271 change_info4 cinfo; 7272 } 7274 union REMOVE4res switch (nfsstat4 status) { 7275 case NFS4_OK: 7276 REMOVE4resok resok4; 7277 default: 7278 void; 7279 } 7281 DESCRIPTION 7283 The REMOVE operation removes (deletes) a directory entry named by 7284 filename from the directory corresponding to the current 7285 filehandle. If the entry in the directory was the last reference 7286 to the corresponding file system object, the object may be 7287 destroyed. 7289 For the directory where the filename was removed, the server 7290 returns change_info4 information in cinfo. With the atomic field 7291 of the change_info4 struct, the server will indicate if the before 7292 and after change attributes were obtained atomically with respect 7293 to the removal. 7295 If the target has a length of 0 (zero), or if target does not obey 7296 the UTF-8 definition, the error NFS4ERR_INVAL will be returned. 7298 IMPLEMENTATION 7300 Draft Specification NFS version 4 Protocol January 2000 7302 NFS versions 2 and 3 required a different operator RMDIR for 7303 directory removal. NFS version 4 REMOVE can be used to delete any 7304 directory entry independent of its file type. 7306 The concept of last reference is server specific. However, if the 7307 numlinks field in the previous attributes of the object had the 7308 value 1, the client should not rely on referring to the object via 7309 a file handle. Likewise, the client should not rely on the 7310 resources (disk space, directory entry, and so on.) formerly 7311 associated with the object becoming immediately available. Thus, if 7312 a client needs to be able to continue to access a file after using 7313 REMOVE to remove it, the client should take steps to make sure that 7314 the file will still be accessible. The usual mechanism used is to 7315 use RENAME to rename the file from its old name to a new hidden 7316 name. 7318 ERRORS 7320 NFS4ERR_ACCES 7321 NFS4ERR_BADHANDLE 7322 NFS4ERR_DELAY 7323 NFS4ERR_FHEXPIRED 7324 NFS4ERR_IO 7325 NFS4ERR_MOVED 7326 NFS4ERR_NAMETOOLONG 7327 NFS4ERR_NOENT 7328 NFS4ERR_NOFILEHANDLE 7329 NFS4ERR_NOTDIR 7330 NFS4ERR_NOTEMPTY 7331 NFS4ERR_NOTSUPP 7332 NFS4ERR_RESOURCE 7333 NFS4ERR_ROFS 7334 NFS4ERR_SERVERFAULT 7335 NFS4ERR_STALE 7336 NFS4ERR_WRONGSEC 7338 Draft Specification NFS version 4 Protocol January 2000 7340 14.2.27. Operation 29: RENAME - Rename Directory Entry 7342 SYNOPSIS 7344 (sfh), oldname (cfh), newname -> source_change_info, 7345 target_change_info 7347 ARGUMENT 7349 struct RENAME4args { 7350 /* SAVED_FH: source directory */ 7351 component4 oldname; 7352 /* CURRENT_FH: target directory */ 7353 component4 newname; 7354 }; 7356 RESULT 7358 struct RENAME4resok { 7359 change_info4 source_cinfo; 7360 change_info4 target_cinfo; 7361 }; 7363 union RENAME4res switch (nfsstat4 status) { 7364 case NFS4_OK: 7365 RENAME4resok resok4; 7366 default: 7367 void; 7368 }; 7370 DESCRIPTION 7372 The RENAME operation renames the object identified by oldname in 7373 the source directory corresponding to the saved filehandle, as set 7374 by the SAVEFH operation, to newname in the target directory 7375 corresponding to the current filehandle. The operation is required 7376 to be atomic to the client. Source and target directories must 7377 reside on the same file system on the server. 7379 If the target directory already contains an entry with the name, 7380 newname, the source object must be compatible with the target: 7381 either both are non-directories or both are directories and the 7382 target must be empty. If compatible, the existing target is 7383 removed before the rename occurs. If they are not compatible or if 7384 the target is a directory but not empty, the server will return the 7386 Draft Specification NFS version 4 Protocol January 2000 7388 error, NFS4ERR_EXIST. 7390 If oldname and newname both refer to the same file (they might be 7391 hard links of each other), then RENAME should perform no action and 7392 return success. 7394 For both directories involved in the RENAME, the server returns 7395 change_info4 information. With the atomic field of the 7396 change_info4 struct, the server will indicate if the before and 7397 after change attributes were obtained atomically with respect to 7398 the rename. 7400 If the oldname or newname has a length of 0 (zero), or if oldname 7401 or newname does not obey the UTF-8 definition, the error 7402 NFS4ERR_INVAL will be returned. 7404 IMPLEMENTATION 7406 The RENAME operation must be atomic to the client. The statement 7407 "source and target directories must reside on the same file system 7408 on the server" means that the fsid fields in the attributes for the 7409 directories are the same. If they reside on different file systems, 7410 the error, NFS4ERR_XDEV, is returned. Even though the operation is 7411 atomic, the status, NFS4ERR_MLINK, may be returned if the server 7412 used a "unlink/link/unlink" sequence internally. 7414 A filehandle may or may not become stale or expire on a rename. 7415 However, server implementors are strongly encouraged to attempt to 7416 keep file handles from becoming stale or expiring in this fashion. 7418 On some servers, the filenames, "." and "..", are illegal as either 7419 oldname or newname. In addition, neither oldname nor newname can 7420 be an alias for the source directory. These servers will return 7421 the error, NFS4ERR_INVAL, in these cases. 7423 ERRORS 7425 NFS4ERR_ACCES 7426 NFS4ERR_BADHANDLE 7427 NFS4ERR_DELAY 7428 NFS4ERR_DQUOT 7429 NFS4ERR_EXIST 7430 NFS4ERR_FHEXPIRED 7431 NFS4ERR_INVAL 7432 NFS4ERR_IO 7434 Draft Specification NFS version 4 Protocol January 2000 7436 NFS4ERR_ISDIR 7437 NFS4ERR_MLINK 7438 NFS4ERR_MOVED 7439 NFS4ERR_NAMETOOLONG 7440 NFS4ERR_NOENT 7441 NFS4ERR_NOFILEHANDLE 7442 NFS4ERR_NOSPC 7443 NFS4ERR_NOTDIR 7444 NFS4ERR_NOTEMPTY 7445 NFS4ERR_NOTSUPP 7446 NFS4ERR_RESOURCE 7447 NFS4ERR_ROFS 7448 NFS4ERR_SERVERFAULT 7449 NFS4ERR_STALE 7450 NFS4ERR_WRONGSEC 7451 NFS4ERR_XDEV 7453 Draft Specification NFS version 4 Protocol January 2000 7455 14.2.28. Operation 30: RENEW - Renew a Lease 7457 SYNOPSIS 7459 stateid -> () 7461 ARGUMENT 7463 struct RENEW4args { 7464 stateid4 stateid; 7465 }; 7467 RESULT 7469 struct RENEW4res { 7470 nfsstat4 status; 7471 }; 7473 DESCRIPTION 7475 The RENEW operation is used by the client to renew leases which it 7476 currently holds at a server. In processing the RENEW request, the 7477 server renews all leases associated with the client. The 7478 associated leases are determined by the client id provided via the 7479 SETCLIENTID procedure. 7481 The stateid for RENEW may not be one of the special stateids 7482 consisting of all bits 0 (zero) or all bits 1. 7484 IMPLEMENTATION 7486 ERRORS 7488 NFS4ERR_BAD_STATEID 7489 NFS4ERR_EXPIRED 7490 NFS4ERR_GRACE 7491 NFS4ERR_INVAL 7492 NFS4ERR_MOVED 7493 NFS4ERR_OLD_STATEID 7494 NFS4ERR_RESOURCE 7495 NFS4ERR_SERVERFAULT 7496 NFS4ERR_STALE_STATEID 7498 Draft Specification NFS version 4 Protocol January 2000 7500 NFS4ERR_WRONGSEC 7502 Draft Specification NFS version 4 Protocol January 2000 7504 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle 7506 SYNOPSIS 7508 (sfh) -> (cfh) 7510 ARGUMENT 7512 /* SAVED_FH: */ 7513 void; 7515 RESULT 7517 struct RESTOREFH4res { 7518 /* CURRENT_FH: value of saved fh */ 7519 nfsstat4 status; 7520 }; 7522 DESCRIPTION 7524 Set the current filehandle to the value in the saved filehandle. 7525 If there is no saved filehandle then return an error 7526 NFS4ERR_NOFILEHANDLE. 7528 IMPLEMENTATION 7530 Operations like OPEN and LOOKUP use the current filehandle to 7531 represent a directory and replace it with a new filehandle. 7532 Assuming the previous filehandle was saved with a SAVEFH operator, 7533 the previous filehandle can be restored as the current filehandle. 7534 This is commonly used to obtain post-operation attributes for the 7535 directory, e.g. 7537 PUTFH (directory filehandle) 7538 SAVEFH 7539 GETATTR attrbits (pre-op dir attrs) 7540 CREATE optbits "foo" attrs 7541 GETATTR attrbits (file attributes) 7542 RESTOREFH 7543 GETATTR attrbits (post-op dir attrs) 7545 ERRORS 7547 Draft Specification NFS version 4 Protocol January 2000 7549 NFS4ERR_BADHANDLE 7550 NFS4ERR_FHEXPIRED 7551 NFS4ERR_MOVED 7552 NFS4ERR_NOFILEHANDLE 7553 NFS4ERR_RESOURCE 7554 NFS4ERR_SERVERFAULT 7555 NFS4ERR_STALE 7556 NFS4ERR_WRONGSEC 7558 Draft Specification NFS version 4 Protocol January 2000 7560 14.2.30. Operation 32: SAVEFH - Save Current Filehandle 7562 SYNOPSIS 7564 (cfh) -> (sfh) 7566 ARGUMENT 7568 /* CURRENT_FH: */ 7569 void; 7571 RESULT 7573 struct SAVEFH4res { 7574 /* SAVED_FH: value of current fh */ 7575 nfsstat4 status; 7576 }; 7578 DESCRIPTION 7580 Save the current filehandle. If a previous filehandle was saved 7581 then it is no longer accessible. The saved filehandle can be 7582 restored as the current filehandle with the RESTOREFH operator. 7584 On success, the current filehandle retains its value. 7586 IMPLEMENTATION 7588 ERRORS 7590 NFS4ERR_BADHANDLE 7591 NFS4ERR_FHEXPIRED 7592 NFS4ERR_MOVED 7593 NFS4ERR_NOFILEHANDLE 7594 NFS4ERR_RESOURCE 7595 NFS4ERR_SERVERFAULT 7596 NFS4ERR_STALE 7597 NFS4ERR_WRONGSEC 7599 Draft Specification NFS version 4 Protocol January 2000 7601 14.2.31. Operation 33: SECINFO - Obtain Available Security 7603 SYNOPSIS 7605 (cfh), name -> { secinfo } 7607 ARGUMENT 7609 struct SECINFO4args { 7610 /* CURRENT_FH: */ 7611 component4 name; 7612 }; 7614 RESULT 7616 enum rpc_gss_svc_t { 7617 RPC_GSS_SVC_NONE = 1, 7618 RPC_GSS_SVC_INTEGRITY = 2, 7619 RPC_GSS_SVC_PRIVACY = 3 7620 }; 7622 struct rpcsec_gss_info { 7623 sec_oid4 oid; 7624 qop4 qop; 7625 rpc_gss_svc_t service; 7626 }; 7628 struct secinfo4 { 7629 uint32_t flavor; 7630 opaque flavor_info<>; /* null for AUTH_SYS, AUTH_NONE; 7631 contains rpcsec_gss_info for 7632 RPCSEC_GSS. */ 7633 }; 7635 typedef secinfo4 SECINFO4resok<>; 7637 union SECINFO4res switch (nfsstat4 status) { 7638 case NFS4_OK: 7639 SECINFO4resok resok4; 7640 default: 7641 void; 7642 }; 7644 DESCRIPTION 7646 Draft Specification NFS version 4 Protocol January 2000 7648 The SECINFO operation is used by the client to obtain a list of 7649 valid RPC authentication flavors for a specific file handle, file 7650 name pair. The result will contain an array which represents the 7651 security mechanisms available. The array entries are represented 7652 by the secinfo4 structure. The field 'flavor' will contain a value 7653 of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or RPCSEC_GSS (as 7654 defined in [RFC2203]). 7656 For the flavors, AUTH_NONE, and AUTH_SYS no additional security 7657 information is returned. For a return value of RPCSEC_GSS, a 7658 security triple is returned that contains the mechanism object id 7659 (as defined in [RFC2078]), the quality of protection (as defined in 7660 [RFC2078]) and the service type (as defined in [RFC2203]). It is 7661 possible for SECINFO to return multiple entries with flavor equal 7662 to RPCSEC_GSS with different security triple values. 7664 IMPLEMENTATION 7666 The SECINFO operation is expected to be used by the NFS client when 7667 the error value of NFS4ERR_WRONGSEC is returned from another NFS 7668 operation. This signifies to the client that the server's security 7669 policy is different from what the client is currently using. At 7670 this point, the client is expected to obtain a list of possible 7671 security flavors and choose what best suits its policies. 7673 It is recommended that the client issue the SECINFO call protected 7674 by a security triple that uses either rpc_gss_svc_integrity or 7675 rpc_gss_svc_privacy service. The use of rpc_gss_svc_none would 7676 allow an attacker in the middle to modify the SECINFO results such 7677 that the client might select a weaker algorithm in the set allowed 7678 by server, making the client and/or server vulnerable to further 7679 attacks. 7681 ERRORS 7683 NFS4ERR_BADHANDLE 7684 NFS4ERR_FHEXPIRED 7685 NFS4ERR_MOVED 7686 NFS4ERR_NAMETOOLONG 7687 NFS4ERR_NOENT 7688 NFS4ERR_NOFILEHANDLE 7689 NFS4ERR_NOTDIR 7690 NFS4ERR_RESOURCE 7691 NFS4ERR_SERVERFAULT 7692 NFS4ERR_STALE 7693 NFS4ERR_WRONGSEC 7695 Draft Specification NFS version 4 Protocol January 2000 7697 14.2.32. Operation 34: SETATTR - Set Attributes 7699 SYNOPSIS 7701 (cfh), attrbits, attrvals -> - 7703 ARGUMENT 7705 struct SETATTR4args { 7706 /* CURRENT_FH: target object */ 7707 stateid4 stateid; 7708 fattr4 obj_attributes; 7709 }; 7711 RESULT 7713 struct SETATTR4res { 7714 nfsstat4 status; 7715 bitmap4 attrsset; 7716 }; 7718 DESCRIPTION 7720 The SETATTR operation changes one or more of the attributes of a 7721 file system object. The new attributes are specified with a bitmap 7722 and the attributes that follow the bitmap in bit order. 7724 The stateid is necessary for SETATTRs that change the size of file 7725 (modify the attribute object_size). This stateid represents a 7726 record lock, share reservation, or delegation which must be valid 7727 for the SETATTR to modify the file data. A valid stateid would 7728 always be specified. When the file size is not changed, the 7729 special stateid consisting of all bits 0 (zero) should be used. 7731 On either success or failure of the operation, the server will 7732 return the attrsset bitmask to represent what (if any) attributes 7733 were successfully set. 7735 IMPLEMENTATION 7737 The file size attribute is used to request changes to the size of a 7738 file. A value of 0 (zero) causes the file to be truncated, a value 7739 less than the current size of the file causes data from new size to 7740 the end of the file to be discarded, and a size greater than the 7742 Draft Specification NFS version 4 Protocol January 2000 7744 current size of the file causes logically zeroed data bytes to be 7745 added to the end of the file. Servers are free to implement this 7746 using holes or actual zero data bytes. Clients should not make any 7747 assumptions regarding a server's implementation of this feature, 7748 beyond that the bytes returned will be zeroed. Servers must 7749 support extending the file size via SETATTR. 7751 SETATTR is not guaranteed atomic. A failed SETATTR may partially 7752 change a file's attributes. 7754 Changing the size of a file with SETATTR indirectly changes the 7755 time_modify. A client must account for this as size changes can 7756 result in data deletion. 7758 If server and client times differ, programs that compare client 7759 time to file times can break. A time maintenance protocol should be 7760 used to limit client/server time skew. 7762 If the server cannot successfully set all the attributes it must 7763 return an NFS4ERR_INVAL error. If the server can only support 32 7764 bit offsets and sizes, a SETATTR request to set the size of a file 7765 to larger than can be represented in 32 bits will be rejected with 7766 this same error. 7768 ERRORS 7770 NFS4ERR_ACCES 7771 NFS4ERR_BADHANDLE 7772 NFS4ERR_BAD_STATEID 7773 NFS4ERR_DELAY 7774 NFS4ERR_DENIED 7775 NFS4ERR_DQUOT 7776 NFS4ERR_EXPIRED 7777 NFS4ERR_FBIG 7778 NFS4ERR_FHEXPIRED 7779 NFS4ERR_GRACE 7780 NFS4ERR_INVAL 7781 NFS4ERR_IO 7782 NFS4ERR_MOVED 7783 NFS4ERR_NOFILEHANDLE 7784 NFS4ERR_NOSPC 7785 NFS4ERR_NOTSUPP 7786 NFS4ERR_OLD_STATEID 7787 NFS4ERR_PERM 7788 NFS4ERR_RESOURCE 7789 NFS4ERR_ROFS 7790 NFS4ERR_SERVERFAULT 7792 Draft Specification NFS version 4 Protocol January 2000 7794 NFS4ERR_STALE 7795 NFS4ERR_STALE_STATEID 7796 NFS4ERR_WRONGSEC 7798 Draft Specification NFS version 4 Protocol January 2000 7800 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid 7802 SYNOPSIS 7804 client, callback -> clientid, setclientid_confirm 7806 ARGUMENT 7808 struct SETCLIENTID4args { 7809 nfs_client_id4 client; 7810 cb_client4 callback; 7811 }; 7813 RESULT 7815 struct SETCLIENTID4resok { 7816 clientid4 clientid; 7817 verifier4 setclientid_confirm; 7818 }; 7820 union SETCLIENTID4res switch (nfsstat4 status) { 7821 case NFS4_OK: 7822 SETCLIENTID4resok resok4; 7823 case NFS4ERR_CLID_INUSE: 7824 clientaddr4 client_using; 7825 default: 7826 void; 7827 }; 7829 DESCRIPTION 7831 The SETCLIENTID operation introduces the ability of the client to 7832 notify the server of its intention to use a particular client 7833 identifier and verifier pair. Upon successful completion the 7834 server will return a clientid which is used in subsequent file 7835 locking requests and a confirmation verifier. The client will use 7836 the SETCLIENTID_CONFIRM operation to return the verifier to the 7837 server. At that point, the client may use the clientid in 7838 subsequent operations that require an nfs_lockowner. 7840 The callback information provided in this operation will be used if 7841 the client is provided an open delegation at a future point. 7842 Therefore, the client must correctly reflect the program and port 7843 numbers for the callback program at the time SETCLIENTID is used. 7845 Draft Specification NFS version 4 Protocol January 2000 7847 IMPLEMENTATION 7849 The server takes the verifier and client identification supplied in 7850 the nfs_client_id4 and searches for a match of the client 7851 identification. If no match is found the server saves the 7852 principal/uid information along with the verifier and client 7853 identification and returns a unique clientid that is used as a 7854 shorthand reference to the supplied information. 7856 If the server finds matching client identification and a 7857 corresponding match in principal/uid, the server releases all 7858 locking state for the client and returns a new clientid. 7860 The principal or principal to user identifier mapping is taken from 7861 the credential presented in the RPC. As mentioned, the server will 7862 use the credential and associated principal for the matching with 7863 existing clientids. If the client is a traditional host based 7864 client like a Unix NFS client, then the credential presented may be 7865 the host credential. If the client is a user level client or light 7866 weight client, the credential used may be the end user's 7867 credential. The client should take care in choosing an appropriate 7868 credential since denial of service attacks could be attempted by a 7869 rogue client that has access to the credential. 7871 ERRORS 7873 NFS4ERR_CLID_INUSE 7874 NFS4ERR_INVAL 7875 NFS4ERR_RESOURCE 7876 NFS4ERR_SERVERFAULT 7878 Draft Specification NFS version 4 Protocol January 2000 7880 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 7882 SYNOPSIS 7884 setclientid_confirm -> - 7886 ARGUMENT 7888 struct SETCLIENTID_CONFIRM4args { 7889 verifier4 setclientid_confirm; 7890 }; 7892 RESULT 7894 struct SETCLIENTID_CONFIRM4res { 7895 nfsstat4 status; 7896 }; 7898 DESCRIPTION 7900 This operation is used by the client to confirm the results from a 7901 previous call to SETCLIENTID. The client provides the server 7902 supplied (from a SETCLIENTID response) opaque confirmation 7903 verifier. The server responds with a simple status of success or 7904 failure. 7906 IMPLEMENTATION 7908 The client must use the SETCLIENTID_CONFIRM operation to confirm 7909 its use of client identifier. Once the server receives the valid 7910 confirmation, all state previously held by the client (if 7911 applicable) is kept until the receipt of the SETCLIENTID_CONFIRM is 7912 successful. Upon successful confirmation the server will release 7913 the previous state held on behalf of the client. The server should 7914 choose a confirmation cookie value that is reasonably unique for 7915 the client. 7917 ERRORS 7919 NFS4ERR_CLID_INUSE 7920 NFS4ERR_INVAL 7921 NFS4ERR_RESOURCE 7922 NFS4ERR_SERVERFAULT 7924 Draft Specification NFS version 4 Protocol January 2000 7926 NFS4ERR_STALE_CLIENTID 7928 Draft Specification NFS version 4 Protocol January 2000 7930 14.2.35. Operation 37: VERIFY - Verify Same Attributes 7932 SYNOPSIS 7934 (cfh), attrbits, attrvals -> - 7936 ARGUMENT 7938 struct VERIFY4args { 7939 /* CURRENT_FH: object */ 7940 bitmap4 attr_request; 7941 fattr4 obj_attributes; 7942 }; 7944 RESULT 7946 struct VERIFY4res { 7947 nfsstat4 status; 7948 }; 7950 DESCRIPTION 7952 The VERIFY operation is used to verify that attributes have a value 7953 assumed by the client before proceeding with following operations 7954 in the compound request. If any of the attributes do not match 7955 then the error NFS4ERR_NOT_SAME must be returned. The current 7956 filehandle retains its value after successful completion of the 7957 operation. 7959 IMPLEMENTATION 7961 One possible use of the VERIFY operation is the following compound 7962 sequence. With this the client is attempting to verify that the 7963 file being removed will match what the client expects to be 7964 removed. This sequence can help prevent the unintended deletion of 7965 a file. 7967 PUTFH (directory filehandle) 7968 LOOKUP (file name) 7969 VERIFY (filehandle == fh) 7970 PUTFH (directory filehandle) 7971 REMOVE (file name) 7973 This sequence does not prevent a second client from removing and 7974 creating a new file in the middle of this sequence but it does help 7976 Draft Specification NFS version 4 Protocol January 2000 7978 avoid the unintended result. 7980 ERRORS 7982 NFS4ERR_ACCES 7983 NFS4ERR_BADHANDLE 7984 NFS4ERR_DELAY 7985 NFS4ERR_FHEXPIRED 7986 NFS4ERR_INVAL 7987 NFS4ERR_MOVED 7988 NFS4ERR_NOFILEHANDLE 7989 NFS4ERR_NOTSUPP 7990 NFS4ERR_NOT_SAME 7991 NFS4ERR_RESOURCE 7992 NFS4ERR_SERVERFAULT 7993 NFS4ERR_STALE 7994 NFS4ERR_WRONGSEC 7996 Draft Specification NFS version 4 Protocol January 2000 7998 14.2.36. Operation 38: WRITE - Write to File 8000 SYNOPSIS 8002 (cfh), offset, count, stability, stateid, data -> count, committed, 8003 verifier 8005 ARGUMENT 8007 enum stable_how4 { 8008 UNSTABLE4 = 0, 8009 DATA_SYNC4 = 1, 8010 FILE_SYNC4 = 2 8011 }; 8013 struct WRITE4args { 8014 /* CURRENT_FH: file */ 8015 stateid4 stateid; 8016 offset4 offset; 8017 stable_how4 stable; 8018 opaque data<>; 8019 }; 8021 RESULT 8023 struct WRITE4resok { 8024 count4 count; 8025 stable_how4 committed; 8026 verifier4writeverf; 8027 }; 8029 union WRITE4res switch (nfsstat4 status) { 8030 case NFS4_OK: 8031 WRITE4resok resok4; 8032 default: 8033 void; 8034 }; 8036 DESCRIPTION 8038 The WRITE operation is used to write data to a regular file. The 8039 target file is specified by the current filehandle. The offset 8040 specifies the offset where the data should be written. An offset 8041 of 0 (zero) specifies that the write should start at the beginning 8042 of the file. The count represents the number of bytes of data that 8044 Draft Specification NFS version 4 Protocol January 2000 8046 are to be written. If the count is 0 (zero), the WRITE will 8047 succeed and return a count of 0 (zero) subject to permissions 8048 checking. The server may choose to write fewer bytes than 8049 requested by the client. 8051 Part of the write request is a specification of how the write is to 8052 be performed. The client specifies with the stable parameter the 8053 method of how the data is to be processed by the server. If stable 8054 is FILE_SYNC4, the server must commit the data written plus all 8055 file system metadata to stable storage before returning results. 8056 This corresponds to the NFS version 2 protocol semantics. Any 8057 other behavior constitutes a protocol violation. If stable is 8058 DATA_SYNC4, then the server must commit all of the data to stable 8059 storage and enough of the metadata to retrieve the data before 8060 returning. The server implementor is free to implement DATA_SYNC4 8061 in the same fashion as FILE_SYNC4, but with a possible performance 8062 drop. If stable is UNSTABLE4, the server is free to commit any 8063 part of the data and the metadata to stable storage, including all 8064 or none, before returning a reply to the client. There is no 8065 guarantee whether or when any uncommitted data will subsequently be 8066 committed to stable storage. The only guarantees made by the server 8067 are that it will not destroy any data without changing the value of 8068 verf and that it will not commit the data and metadata at a level 8069 less than that requested by the client. 8071 The stateid returned from a previous record lock or share 8072 reservation request is provided as part of the argument. The 8073 stateid is used by the server to verify that the associated lock is 8074 still valid and to update lease timeouts for the client. 8076 Upon successful completion, the following results are returned. 8077 The count result is the number of bytes of data written to the 8078 file. The server may write fewer bytes than requested. If so, the 8079 actual number of bytes written starting at location, offset, is 8080 returned. 8082 The server also returns an indication of the level of commitment of 8083 the data and metadata via committed. If the server committed all 8084 data and metadata to stable storage, committed should be set to 8085 FILE_SYNC4. If the level of commitment was at least as strong as 8086 DATA_SYNC4, then committed should be set to DATA_SYNC4. Otherwise, 8087 committed must be returned as UNSTABLE4. If stable was FILE4_SYNC, 8088 then committed must also be FILE_SYNC4: anything else constitutes a 8089 protocol violation. If stable was DATA_SYNC4, then committed may be 8090 FILE_SYNC4 or DATA_SYNC4: anything else constitutes a protocol 8091 violation. If stable was UNSTABLE4, then committed may be either 8092 FILE_SYNC4, DATA_SYNC4, or UNSTABLE4. 8094 Draft Specification NFS version 4 Protocol January 2000 8096 The final portion of the result is the write verifier, verf. The 8097 write verifier is a cookie that the client can use to determine 8098 whether the server has changed state between a call to WRITE and a 8099 subsequent call to either WRITE or COMMIT. This cookie must be 8100 consistent during a single instance of the NFS version 4 protocol 8101 service and must be unique between instances of the NFS version 4 8102 protocol server, where uncommitted data may be lost. 8104 If a client writes data to the server with the stable argument set 8105 to UNSTABLE4 and the reply yields a committed response of 8106 DATA_SYNC4 or UNSTABLE4, the client will follow up some time in the 8107 future with a COMMIT operation to synchronize outstanding 8108 asynchronous data and metadata with the server's stable storage, 8109 barring client error. It is possible that due to client crash or 8110 other error that a subsequent COMMIT will not be received by the 8111 server. 8113 On success, the current filehandle retains its value. 8115 IMPLEMENTATION 8117 It is possible for the server to write fewer than count bytes of 8118 data. In this case, the server should not return an error unless 8119 no data was written at all. If the server writes less than count 8120 bytes, the client should issue another WRITE to write the remaining 8121 data. 8123 It is assumed that the act of writing data to a file will cause the 8124 time_modified of the file to be updated. However, the 8125 time_modified of the file should not be changed unless the contents 8126 of the file are changed. Thus, a WRITE request with count set to 0 8127 should not cause the time_modified of the file to be updated. 8129 The definition of stable storage has been historically a point of 8130 contention. The following expected properties of stable storage 8131 may help in resolving design issues in the implementation. Stable 8132 storage is persistent storage that survives: 8134 1. Repeated power failures. 8135 2. Hardware failures (of any board, power supply, etc.). 8136 3. Repeated software crashes, including reboot cycle. 8138 This definition does not address failure of the stable storage 8139 module itself. 8141 Draft Specification NFS version 4 Protocol January 2000 8143 The verifier is defined to allow a client to detect different 8144 instances of an NFS version 4 protocol server over which cached, 8145 uncommitted data may be lost. In the most likely case, the verifier 8146 allows the client to detect server reboots. This information is 8147 required so that the client can safely determine whether the server 8148 could have lost cached data. If the server fails unexpectedly and 8149 the client has uncommitted data from previous WRITE requests (done 8150 with the stable argument set to UNSTABLE4 and in which the result 8151 committed was returned as UNSTABLE4 as well) it may not have 8152 flushed cached data to stable storage. The burden of recovery is on 8153 the client and the client will need to retransmit the data to the 8154 server. 8156 A suggested verifier would be to use the time that the server was 8157 booted or the time the server was last started (if restarting the 8158 server without a reboot results in lost buffers). 8160 The committed field in the results allows the client to do more 8161 effective caching. If the server is committing all WRITE requests 8162 to stable storage, then it should return with committed set to 8163 FILE_SYNC4, regardless of the value of the stable field in the 8164 arguments. A server that uses an NVRAM accelerator may choose to 8165 implement this policy. The client can use this to increase the 8166 effectiveness of the cache by discarding cached data that has 8167 already been committed on the server. 8169 Some implementations may return NFS4ERR_NOSPC instead of 8170 NFS4ERR_DQUOT when a user's quota is exceeded. 8172 ERRORS 8174 NFS4ERR_ACCES 8175 NFS4ERR_BADHANDLE 8176 NFS4ERR_BAD_STATEID 8177 NFS4ERR_DELAY 8178 NFS4ERR_DENIED 8179 NFS4ERR_DQUOT 8180 NFS4ERR_EXPIRED 8181 NFS4ERR_FBIG 8182 NFS4ERR_FHEXPIRED 8183 NFS4ERR_GRACE 8184 NFS4ERR_INVAL 8185 NFS4ERR_IO 8186 NFS4ERR_LOCKED 8187 NFS4ERR_MOVED 8188 NFS4ERR_NOFILEHANDLE 8189 NFS4ERR_NOSPC 8191 Draft Specification NFS version 4 Protocol January 2000 8193 NFS4ERR_OLD_STATEID 8194 NFS4ERR_RESOURCE 8195 NFS4ERR_ROFS 8196 NFS4ERR_SERVERFAULT 8197 NFS4ERR_STALE 8198 NFS4ERR_STALE_STATEID 8199 NFS4ERR_WRONGSEC 8201 Draft Specification NFS version 4 Protocol January 2000 8203 15. NFS Version 4 Callback Procedures 8205 The procedures used for callbacks are defined in the following 8206 sections. In the interest of clarity, the terms "client" and 8207 "server" refer to NFS clients and servers, despite the fact that for 8208 an individual callback RPC, the sense of these terms would be 8209 precisely the opposite. 8211 15.1. Procedure 0: CB_NULL - No Operation 8213 SYNOPSIS 8215 8217 ARGUMENT 8219 void; 8221 RESULT 8223 void; 8225 DESCRIPTION 8227 Standard NULL procedure. Void argument, void response. This 8228 procedure has no functionality associated with it. 8230 ERRORS 8232 None. 8234 Draft Specification NFS version 4 Protocol January 2000 8236 15.2. Procedure 1: CB_COMPOUND - Compound Operations 8238 SYNOPSIS 8240 compoundargs -> compoundres 8242 ARGUMENT 8244 enum nfs_cb_opnum4 { 8245 OP_CB_GETATTR = 3, 8246 OP_CB_RECALL = 4 8247 }; 8249 union nfs_cb_argop4 switch (unsigned argop) { 8250 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 8251 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 8252 }; 8254 struct CB_COMPOUND4args { 8255 utf8string tag; 8256 uint32_t minorversion; 8257 nfs_cb_argop4 argarray<>; 8258 }; 8260 RESULT 8262 union nfs_cb_resop4 switch (unsigned resop){ 8263 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 8264 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 8265 }; 8267 struct CB_COMPOUND4args { 8268 utf8string tag; 8269 uint32_t minorversion; 8270 nfs_cb_argop4 argarray<>; 8271 }; 8273 struct CB_COMPOUND4res { 8274 nfsstat4 status; 8275 utf8string tag; 8276 nfs_cb_resop4 resarray<>; 8277 }; 8279 DESCRIPTION 8281 Draft Specification NFS version 4 Protocol January 2000 8283 The CB_COMPOUND procedure is used to combine one or more of the 8284 callback procedures into a single RPC request. The main callback 8285 RPC program has two main procedures: CB_NULL and CB_COMPOUND. All 8286 other operations use the CB_COMPOUND procedure as a wrapper. 8288 In the processing of the CB_COMPOUND procedure, the client may find 8289 that it does not have the available resources to execute any or all 8290 of the operations within the CB_COMPOUND sequence. In this case, 8291 the error NFS4ERR_RESOURCE will be returned for the particular 8292 operation within the CB_COMPOUND procedure where the resource 8293 exhaustion occurred. This assumes that all previous operations 8294 within the CB_COMPOUND sequence have been evaluated successfully. 8296 Contained within the CB_COMPOUND results is a 'status' field. This 8297 status must be equivalent to the status of the last operation that 8298 was executed within the CB_COMPOUND procedure. Therefore, if an 8299 operation incurred an error then the 'status' value will be the 8300 same error value as is being returned for the operation that 8301 failed. 8303 IMPLEMENTATION 8305 The CB_COMPOUND procedure is used to combine individual operations 8306 into a single RPC request. The client interprets each of the 8307 operations in turn. If an operation is executed by the client and 8308 the status of that operation is NFS4_OK, then the next operation in 8309 the CB_COMPOUND procedure is executed. The client continues this 8310 process until there are no more operations to be executed or one of 8311 the operations has a status value other than NFS4_OK. 8313 ERRORS 8315 All errors defined in the protocol 8317 Draft Specification NFS version 4 Protocol January 2000 8319 15.2.1. Operation 3: CB_GETATTR - Get Attributes 8321 SYNOPSIS 8323 fh, attrbits -> attrbits, attrvals 8325 ARGUMENT 8327 struct CB_GETATTR4args { 8328 nfs_fh4 fh; 8329 bitmap4 attr_request; 8330 }; 8332 RESULT 8334 struct CB_GETATTR4resok { 8335 fattr4 obj_attributes; 8336 }; 8338 union CB_GETATTR4res switch (nfsstat4 status) { 8339 case NFS4_OK: 8340 CB_GETATTR4resok resok4; 8341 default: 8342 void; 8343 }; 8345 DESCRIPTION 8347 The CB_GETATTR operation is used to obtain the attributes modified 8348 by an open delegate to allow the server to respond to GETATTR 8349 requests for a file which is the subject of an open delegation. 8351 If the handle specified is not one for which the client holds a 8352 write open delegation, an NFS4ERR_BADHANDLE error is returned. 8354 IMPLEMENTATION 8356 The client returns attrbits and the associated attribute values 8357 only for attributes that it may change (change, time_modify, 8358 object_size). It may further limit the response to attributes that 8359 it has in fact changed during the scope of the delegation. 8361 Draft Specification NFS version 4 Protocol January 2000 8363 ERRORS 8365 NFS4ERR_BADHANDLE 8366 NFS4ERR_RESOURCE 8368 Draft Specification NFS version 4 Protocol January 2000 8370 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation 8372 SYNOPSIS 8374 stateid, truncate, fh -> status 8376 ARGUMENT 8378 struct CB_RECALL4args { 8379 stateid4 stateid; 8380 bool truncate; 8381 nfs_fh4 fh; 8382 }; 8384 RESULT 8386 struct CB_RECALL4res { 8387 nfsstat4 status; 8388 }; 8390 DESCRIPTION 8392 The CB_RECALL operation is used to begin the process of recalling 8393 an open delegation and returning it to the server. 8395 The truncate flag is used to optimize recall for a file which is 8396 about to be truncated to zero. When it is set, the client is freed 8397 of obligation to propagate modified data for the file to the 8398 server, since this data is irrelevant. 8400 If the handle specified is not one for which the client holds an 8401 open delegation, an NFS4ERR_BADHANDLE error is returned. 8403 If the stateid specified is not one corresponding to an open 8404 delegation for the file specified by the filehandle, an 8405 NFS4ERR_BAD_STATEID is returned. 8407 IMPLEMENTATION 8409 The client should reply to the callback immediately. Replying does 8410 not complete the recall. The recall is not complete until the 8411 delegation is returned using a DELEGRETURN. 8413 Draft Specification NFS version 4 Protocol January 2000 8415 ERRORS 8417 NFS4ERR_BADHANDLE 8418 NFS4ERR_BAD_STATEID 8419 NFS4ERR_RESOURCE 8421 Draft Specification NFS version 4 Protocol January 2000 8423 16. Security Considerations 8425 The major security feature to consider is the authentication of the 8426 user making the request of NFS service. Consideration should also be 8427 given to the integrity and privacy of this NFS request. These 8428 specific issues are discussed as part of the section on "RPC and 8429 Security Flavor". 8431 Draft Specification NFS version 4 Protocol January 2000 8433 17. IANA Considerations 8435 17.1. Named Attribute Definition 8437 The NFS version 4 protocol provides for the association of named 8438 attributes to files. The name space identifiers for these attributes 8439 are defined as string names. The protocol does not define the 8440 specific assignment of the name space for these file attributes; the 8441 application developer or system vendor is allowed to define the 8442 attribute, its semantics, and the associated name. Even though this 8443 name space will not be specifically controlled to prevent collisions, 8444 the application developer or system vendor is strongly encouraged to 8445 provide the name assignment and associated semantics for attributes 8446 via an information RFC. This will provide for interoperability where 8447 common interests exist. 8449 Draft Specification NFS version 4 Protocol January 2000 8451 18. RPC definition file 8453 /* 8454 * Copyright (C) The Internet Society (1998,2000). 8455 * All Rights Reserved. 8456 */ 8458 /* 8459 * nfs4_prot.x 8460 * 8461 */ 8463 %#pragma ident "@(#)nfs4_prot.x 1.87 00/01/20" 8465 /* 8466 * Basic typedefs for RFC 1832 data type definitions 8467 */ 8468 typedef int int32_t; 8469 typedef unsigned int uint32_t; 8470 typedef hyper int64_t; 8471 typedef unsigned hyper uint64_t; 8473 /* 8474 * Sizes 8475 */ 8476 const NFS4_FHSIZE = 128; 8477 const NFS4_VERIFIER_SIZE = 8; 8479 /* 8480 * File types 8481 */ 8482 enum nfs_ftype4 { 8483 NF4REG = 1, /* Regular File */ 8484 NF4DIR = 2, /* Directory */ 8485 NF4BLK = 3, /* Special File - block device */ 8486 NF4CHR = 4, /* Special File - character device */ 8487 NF4LNK = 5, /* Symbolic Link */ 8488 NF4SOCK = 6, /* Special File - socket */ 8489 NF4FIFO = 7, /* Special File - fifo */ 8490 NF4ATTRDIR = 8, /* Attribute Directory */ 8491 NF4NAMEDATTR = 9 /* Named Attribute */ 8492 }; 8494 /* 8495 * Error status 8496 */ 8497 enum nfsstat4 { 8498 NFS4_OK = 0, 8500 Draft Specification NFS version 4 Protocol January 2000 8502 NFS4ERR_PERM = 1, 8503 NFS4ERR_NOENT = 2, 8504 NFS4ERR_IO = 5, 8505 NFS4ERR_NXIO = 6, 8506 NFS4ERR_ACCES = 13, 8507 NFS4ERR_EXIST = 17, 8508 NFS4ERR_XDEV = 18, 8509 NFS4ERR_NODEV = 19, 8510 NFS4ERR_NOTDIR = 20, 8511 NFS4ERR_ISDIR = 21, 8512 NFS4ERR_INVAL = 22, 8513 NFS4ERR_FBIG = 27, 8514 NFS4ERR_NOSPC = 28, 8515 NFS4ERR_ROFS = 30, 8516 NFS4ERR_MLINK = 31, 8517 NFS4ERR_NAMETOOLONG = 63, 8518 NFS4ERR_NOTEMPTY = 66, 8519 NFS4ERR_DQUOT = 69, 8520 NFS4ERR_STALE = 70, 8521 NFS4ERR_BADHANDLE = 10001, 8522 NFS4ERR_NOT_SYNC = 10002, 8523 NFS4ERR_BAD_COOKIE = 10003, 8524 NFS4ERR_NOTSUPP = 10004, 8525 NFS4ERR_TOOSMALL = 10005, 8526 NFS4ERR_SERVERFAULT = 10006, 8527 NFS4ERR_BADTYPE = 10007, 8528 NFS4ERR_DELAY = 10008, 8529 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 8530 NFS4ERR_DENIED = 10010,/* lock unavailable */ 8531 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 8532 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 8533 NFS4ERR_GRACE = 10013,/* in grace period */ 8534 NFS4ERR_FHEXPIRED = 10014,/* file handle expired */ 8535 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 8536 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 8537 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 8538 NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ 8539 NFS4ERR_MOVED = 10019,/* filesystem relocated */ 8540 NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */ 8541 NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */ 8542 NFS4ERR_STALE_CLIENTID = 10022, 8543 NFS4ERR_STALE_STATEID = 10023, 8544 NFS4ERR_OLD_STATEID = 10024, 8545 NFS4ERR_BAD_STATEID = 10025, 8546 NFS4ERR_BAD_SEQID = 10026, 8547 NFS4ERR_NOT_SAME = 10027,/* verify - attrs not same */ 8548 NFS4ERR_LOCK_RANGE = 10028, 8549 NFS4ERR_SYMLINK = 10029 8551 Draft Specification NFS version 4 Protocol January 2000 8553 }; 8555 /* 8556 * Basic data types 8557 */ 8558 typedef uint32_t bitmap4<>; 8559 typedef uint64_t offset4; 8560 typedef uint32_t count4; 8561 typedef uint64_t length4; 8562 typedef uint64_t clientid4; 8563 typedef uint64_t stateid4; 8564 typedef uint32_t seqid4; 8565 typedef opaque utf8string<>; 8566 typedef utf8string component4; 8567 typedef component4 pathname4<>; 8568 typedef uint64_t nfs_lockid4; 8569 typedef uint64_t nfs_cookie4; 8570 typedef utf8string linktext4; 8571 typedef opaque sec_oid4<>; 8572 typedef uint32_t qop4; 8573 typedef uint32_t mode4; 8574 typedef uint64_t changeid4; 8575 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 8577 /* 8578 * Timeval 8579 */ 8580 struct nfstime4 { 8581 int64_t seconds; 8582 uint32_t nseconds; 8583 }; 8585 /* 8586 * File access handle 8587 */ 8588 typedef opaque nfs_fh4; 8590 /* 8591 * File attribute definitions 8592 */ 8594 /* 8595 * FSID structure for major/minor 8596 */ 8597 struct fsid4 { 8598 uint64_t major; 8599 uint64_t minor; 8601 Draft Specification NFS version 4 Protocol January 2000 8603 }; 8605 /* 8606 * Filesystem locations attribute for relocation/migration 8607 */ 8608 struct fs_location4 { 8609 utf8string server<>; 8610 pathname4 rootpath; 8611 }; 8613 struct fs_locations4 { 8614 pathname4 fs_root; 8615 fs_location4 locations<>; 8616 }; 8618 /* 8619 * Various Access Control Entry definitions 8620 */ 8622 /* 8623 * Mask that indicates which Access Control Entries are supported. 8624 * Values for the fattr4_aclsupport attribute. 8625 */ 8626 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 8627 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 8628 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 8629 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 8631 typedef uint32_t acetype4; 8633 /* 8634 * acetype4 values, others can be added as needed. 8635 */ 8636 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 8637 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 8638 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 8639 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 8641 /* 8642 * ACE flag 8643 */ 8644 typedef uint32_t aceflag4; 8646 /* 8647 * ACE flag values 8648 */ 8650 Draft Specification NFS version 4 Protocol January 2000 8652 const ACE4_FILE_INHERIT_ACE = 0x00000001; 8653 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 8654 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 8655 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 8656 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 8657 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 8658 const ACE4_IDENTIFIER_GROUP = 0x00000040; 8660 /* 8661 * ACE mask 8662 */ 8663 typedef uint32_t acemask4; 8665 /* 8666 * ACE mask values 8667 */ 8668 const ACE4_READ_DATA = 0x00000001; 8669 const ACE4_LIST_DIRECTORY = 0x00000001; 8670 const ACE4_WRITE_DATA = 0x00000002; 8671 const ACE4_ADD_FILE = 0x00000002; 8672 const ACE4_APPEND_DATA = 0x00000004; 8673 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 8674 const ACE4_READ_NAMED_ATTRS = 0x00000008; 8675 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 8676 const ACE4_EXECUTE = 0x00000020; 8677 const ACE4_DELETE_CHILD = 0x00000040; 8678 const ACE4_READ_ATTRIBUTES = 0x00000080; 8679 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 8681 const ACE4_DELETE = 0x00010000; 8682 const ACE4_READ_ACL = 0x00020000; 8683 const ACE4_WRITE_ACL = 0x00040000; 8684 const ACE4_WRITE_OWNER = 0x00080000; 8685 const ACE4_SYNCHRONIZE = 0x00100000; 8687 /* 8688 * ACE4_GENERIC_READ -- defined as combination of 8689 * ACE4_READ_ACL | 8690 * ACE4_READ_DATA | 8691 * ACE4_READ_ATTRIBUTES | 8692 * ACE4_SYNCHRONIZE 8693 */ 8695 const ACE4_GENERIC_READ = 0x00120081; 8697 /* 8698 * ACE4_GENERIC_WRITE -- defined as combination of 8700 Draft Specification NFS version 4 Protocol January 2000 8702 * ACE4_READ_ACL | 8703 * ACE4_WRITE_DATA | 8704 * ACE4_WRITE_ATTRIBUTES | 8705 * ACE4_WRITE_ACL | 8706 * ACE4_APPEND_DATA | 8707 * ACE4_SYNCHRONIZE 8708 */ 8709 const ACE4_GENERIC_WRITE = 0x00160102; 8711 /* 8712 * ACE4_GENERIC_EXECUTE -- defined as combination of 8713 * ACE4_READ_ACL 8714 * ACE4_READ_ATTRIBUTES 8715 * ACE4_EXECUTE 8716 * ACE4_SYNCHRONIZE 8717 */ 8718 const ACE4_GENERIC_EXECUTE = 0x001200A0; 8720 /* 8721 * Access Control Entry definition 8722 */ 8723 struct nfsace4 { 8724 acetype4 type; 8725 aceflag4 flag; 8726 acemask4 access_mask; 8727 utf8string who; 8728 }; 8730 /* 8731 * Special data/attribute associated with 8732 * file types NF4BLK and NF4CHR. 8733 */ 8734 struct specdata4 { 8735 uint32_t specdata1; 8736 uint32_t specdata2; 8737 }; 8739 /* 8740 * Values for fattr4_fh_expire_type 8741 */ 8742 const FH4_PERSISTENT = 0x00000000; 8743 const FH4_NOEXPIRE_WITH_OPEN = 0x00000001; 8744 const FH4_VOLATILE_ANY = 0x00000002; 8745 const FH4_VOL_MIGRATION = 0x00000004; 8746 const FH4_VOL_RENAME = 0x00000008; 8748 Draft Specification NFS version 4 Protocol January 2000 8750 typedef bitmap4 fattr4_supported_attrs; 8751 typedef nfs_ftype4 fattr4_type; 8752 typedef uint32_t fattr4_fh_expire_type; 8753 typedef changeid4 fattr4_change; 8754 typedef uint64_t fattr4_size; 8755 typedef bool fattr4_link_support; 8756 typedef bool fattr4_symlink_support; 8757 typedef bool fattr4_named_attr; 8758 typedef fsid4 fattr4_fsid; 8759 typedef bool fattr4_unique_handles; 8760 typedef uint32_t fattr4_lease_time; 8761 typedef nfsstat4 fattr4_rdattr_error; 8763 typedef nfsace4 fattr4_acl<>; 8764 typedef uint32_t fattr4_aclsupport; 8765 typedef bool fattr4_archive; 8766 typedef bool fattr4_cansettime; 8767 typedef bool fattr4_case_insensitive; 8768 typedef bool fattr4_case_preserving; 8769 typedef bool fattr4_chown_restricted; 8770 typedef uint64_t fattr4_fileid; 8771 typedef uint64_t fattr4_files_avail; 8772 typedef nfs_fh4 fattr4_filehandle; 8773 typedef uint64_t fattr4_files_free; 8774 typedef uint64_t fattr4_files_total; 8775 typedef fs_locations4 fattr4_fs_locations; 8776 typedef bool fattr4_hidden; 8777 typedef bool fattr4_homogeneous; 8778 typedef uint64_t fattr4_maxfilesize; 8779 typedef uint32_t fattr4_maxlink; 8780 typedef uint32_t fattr4_maxname; 8781 typedef uint64_t fattr4_maxread; 8782 typedef uint64_t fattr4_maxwrite; 8783 typedef utf8string fattr4_mimetype; 8784 typedef mode4 fattr4_mode; 8785 typedef bool fattr4_no_trunc; 8786 typedef uint32_t fattr4_numlinks; 8787 typedef utf8string fattr4_owner; 8788 typedef utf8string fattr4_owner_group; 8789 typedef uint64_t fattr4_quota_hard; 8790 typedef uint64_t fattr4_quota_soft; 8791 typedef uint64_t fattr4_quota_used; 8792 typedef specdata4 fattr4_rawdev; 8793 typedef uint64_t fattr4_space_avail; 8794 typedef uint64_t fattr4_space_free; 8795 typedef uint64_t fattr4_space_total; 8796 typedef uint64_t fattr4_space_used; 8797 typedef bool fattr4_system; 8799 Draft Specification NFS version 4 Protocol January 2000 8801 typedef nfstime4 fattr4_time_access; 8802 typedef nfstime4 fattr4_time_backup; 8803 typedef nfstime4 fattr4_time_create; 8804 typedef nfstime4 fattr4_time_delta; 8805 typedef nfstime4 fattr4_time_metadata; 8806 typedef nfstime4 fattr4_time_modify; 8807 typedef utf8string fattr4_version; 8808 typedef nfstime4 fattr4_volatility; 8810 /* 8811 * Mandatory Attributes 8812 */ 8813 const FATTR4_SUPPORTED_ATTRS = 0; 8814 const FATTR4_TYPE = 1; 8815 const FATTR4_PERSISTENT_FH = 2; 8816 const FATTR4_CHANGE = 3; 8817 const FATTR4_SIZE = 4; 8818 const FATTR4_LINK_SUPPORT = 5; 8819 const FATTR4_SYMLINK_SUPPORT = 6; 8820 const FATTR4_NAMED_ATTR = 7; 8821 const FATTR4_FSID = 8; 8822 const FATTR4_UNIQUE_HANDLES = 9; 8823 const FATTR4_LEASE_TIME = 10; 8824 const FATTR4_RDATTR_ERROR = 11; 8826 /* 8827 * Recommended Attributes 8828 */ 8829 const FATTR4_ACL = 12; 8830 const FATTR4_ARCHIVE = 13; 8831 const FATTR4_CANSETTIME = 14; 8832 const FATTR4_CASE_INSENSITIVE = 15; 8833 const FATTR4_CASE_PRESERVING = 16; 8834 const FATTR4_CHOWN_RESTRICTED = 17; 8835 const FATTR4_FILEHANDLE = 18; 8836 const FATTR4_FILEID = 19; 8837 const FATTR4_FILES_AVAIL = 20; 8838 const FATTR4_FILES_FREE = 21; 8839 const FATTR4_FILES_TOTAL = 22; 8840 const FATTR4_FS_LOCATIONS = 23; 8841 const FATTR4_HIDDEN = 24; 8842 const FATTR4_HOMOGENEOUS = 25; 8843 const FATTR4_MAXFILESIZE = 26; 8844 const FATTR4_MAXLINK = 27; 8845 const FATTR4_MAXNAME = 28; 8846 const FATTR4_MAXREAD = 29; 8847 const FATTR4_MAXWRITE = 30; 8849 Draft Specification NFS version 4 Protocol January 2000 8851 const FATTR4_MIMETYPE = 31; 8852 const FATTR4_MODE = 32; 8853 const FATTR4_NO_TRUNC = 33; 8854 const FATTR4_NUMLINKS = 34; 8855 const FATTR4_OWNER = 35; 8856 const FATTR4_OWNER_GROUP = 36; 8857 const FATTR4_QUOTA_HARD = 37; 8858 const FATTR4_QUOTA_SOFT = 38; 8859 const FATTR4_QUOTA_USED = 39; 8860 const FATTR4_RAWDEV = 40; 8861 const FATTR4_SPACE_AVAIL = 41; 8862 const FATTR4_SPACE_FREE = 42; 8863 const FATTR4_SPACE_TOTAL = 43; 8864 const FATTR4_SPACE_USED = 44; 8865 const FATTR4_SYSTEM = 45; 8866 const FATTR4_TIME_ACCESS = 46; 8867 const FATTR4_TIME_BACKUP = 47; 8868 const FATTR4_TIME_CREATE = 48; 8869 const FATTR4_TIME_DELTA = 49; 8870 const FATTR4_TIME_METADATA = 50; 8871 const FATTR4_TIME_MODIFY = 51; 8872 const FATTR4_VERSION = 52; 8873 const FATTR4_VOLATILITY = 53; 8875 typedef opaque attrlist4<>; 8877 /* 8878 * File attribute container 8879 */ 8880 struct fattr4 { 8881 bitmap4 attrmask; 8882 attrlist4 attr_vals; 8883 }; 8885 /* 8886 * Change info for the client 8887 */ 8888 struct change_info4 { 8889 bool atomic; 8890 changeid4 before; 8891 changeid4 after; 8892 }; 8894 struct clientaddr4 { 8895 /* see struct rpcb in RFC 1833 */ 8896 string r_netid<>; /* network id */ 8897 string r_addr<>; /* universal address */ 8899 Draft Specification NFS version 4 Protocol January 2000 8901 }; 8903 /* 8904 * Callback program info as provided by the client 8905 */ 8906 struct cb_client4 { 8907 unsigned int cb_program; 8908 clientaddr4 cb_location; 8909 }; 8911 /* 8912 * Client ID 8913 */ 8914 struct nfs_client_id4 { 8915 verifier4 verifier; 8916 opaque id<>; 8917 }; 8919 struct nfs_lockowner4 { 8920 clientid4 clientid; 8921 opaque owner<>; 8922 }; 8924 enum nfs_lock_type4 { 8925 READ_LT = 1, 8926 WRITE_LT = 2, 8927 READW_LT = 3, /* blocking read */ 8928 WRITEW_LT = 4 /* blocking write */ 8929 }; 8931 /* 8932 * ACCESS: Check access permission 8933 */ 8934 const ACCESS4_READ = 0x00000001; 8935 const ACCESS4_LOOKUP = 0x00000002; 8936 const ACCESS4_MODIFY = 0x00000004; 8937 const ACCESS4_EXTEND = 0x00000008; 8938 const ACCESS4_DELETE = 0x00000010; 8939 const ACCESS4_EXECUTE = 0x00000020; 8941 struct ACCESS4args { 8942 /* CURRENT_FH: object */ 8943 uint32_t access; 8944 }; 8946 struct ACCESS4resok { 8947 uint32_t supported; 8948 uint32_t access; 8950 Draft Specification NFS version 4 Protocol January 2000 8952 }; 8954 union ACCESS4res switch (nfsstat4 status) { 8955 case NFS4_OK: 8956 ACCESS4resok resok4; 8957 default: 8958 void; 8959 }; 8961 /* 8962 * CLOSE: Close a file and release share locks 8963 */ 8964 struct CLOSE4args { 8965 /* CURRENT_FH: object */ 8966 seqid4 seqid; 8967 stateid4 stateid; 8968 }; 8970 union CLOSE4res switch (nfsstat4 status) { 8971 case NFS4_OK: 8972 stateid4 stateid; 8973 default: 8974 void; 8975 }; 8977 /* 8978 * COMMIT: Commit cached data on server to stable storage 8979 */ 8980 struct COMMIT4args { 8981 /* CURRENT_FH: file */ 8982 offset4 offset; 8983 count4 count; 8984 }; 8986 struct COMMIT4resok { 8987 verifier4 writeverf; 8988 }; 8990 union COMMIT4res switch (nfsstat4 status) { 8991 case NFS4_OK: 8992 COMMIT4resok resok4; 8993 default: 8994 void; 8995 }; 8997 /* 8998 * CREATE: Create a file 9000 Draft Specification NFS version 4 Protocol January 2000 9002 */ 9003 union createtype4 switch (nfs_ftype4 type) { 9004 case NF4LNK: 9005 linktext4 linkdata; 9006 case NF4BLK: 9007 case NF4CHR: 9008 specdata4 devdata; 9009 case NF4SOCK: 9010 case NF4FIFO: 9011 case NF4DIR: 9012 void; 9013 }; 9015 struct CREATE4args { 9016 /* CURRENT_FH: directory for creation */ 9017 component4 objname; 9018 createtype4 objtype; 9019 }; 9021 struct CREATE4resok { 9022 change_info4 cinfo; 9023 }; 9025 union CREATE4res switch (nfsstat4 status) { 9026 case NFS4_OK: 9027 CREATE4resok resok4; 9028 default: 9029 void; 9030 }; 9032 /* 9033 * DELEGPURGE: Purge Delegations Awaiting Recovery 9034 */ 9035 struct DELEGPURGE4args { 9036 clientid4 clientid; 9037 }; 9039 struct DELEGPURGE4res { 9040 nfsstat4 status; 9041 }; 9043 /* 9044 * DELEGRETURN: Return a delegation 9045 */ 9046 struct DELEGRETURN4args { 9047 stateid4 stateid; 9048 }; 9050 Draft Specification NFS version 4 Protocol January 2000 9052 struct DELEGRETURN4res { 9053 nfsstat4 status; 9054 }; 9056 /* 9057 * GETATTR: Get file attributes 9058 */ 9059 struct GETATTR4args { 9060 /* CURRENT_FH: directory or file */ 9061 bitmap4 attr_request; 9062 }; 9064 struct GETATTR4resok { 9065 fattr4 obj_attributes; 9066 }; 9068 union GETATTR4res switch (nfsstat4 status) { 9069 case NFS4_OK: 9070 GETATTR4resok resok4; 9071 default: 9072 void; 9073 }; 9075 /* 9076 * GETFH: Get current filehandle 9077 */ 9078 struct GETFH4resok { 9079 nfs_fh4 object; 9080 }; 9082 union GETFH4res switch (nfsstat4 status) { 9083 case NFS4_OK: 9084 GETFH4resok resok4; 9085 default: 9086 void; 9087 }; 9089 /* 9090 * LINK: Create link to an object 9091 */ 9092 struct LINK4args { 9093 /* SAVED_FH: source object */ 9094 /* CURRENT_FH: target directory */ 9095 component4 newname; 9096 }; 9098 struct LINK4resok { 9099 change_info4 cinfo; 9101 Draft Specification NFS version 4 Protocol January 2000 9103 }; 9105 union LINK4res switch (nfsstat4 status) { 9106 case NFS4_OK: 9107 LINK4resok resok4; 9108 default: 9109 void; 9110 }; 9112 /* 9113 * LOCK/LOCKT/LOCKU: Record lock management 9114 */ 9115 struct LOCK4args { 9116 /* CURRENT_FH: file */ 9117 nfs_lock_type4 locktype; 9118 seqid4 seqid; 9119 bool reclaim; 9120 stateid4 stateid; 9121 offset4 offset; 9122 length4 length; 9123 }; 9125 struct LOCK4denied { 9126 nfs_lockowner4 owner; 9127 offset4 offset; 9128 length4 length; 9129 }; 9131 union LOCK4res switch (nfsstat4 status) { 9132 case NFS4_OK: 9133 stateid4 stateid; 9134 case NFS4ERR_DENIED: 9135 LOCK4denied denied; 9136 default: 9137 void; 9138 }; 9140 struct LOCKT4args { 9141 /* CURRENT_FH: file */ 9142 nfs_lock_type4 locktype; 9143 nfs_lockowner4 owner; 9144 offset4 offset; 9145 length4 length; 9146 }; 9148 union LOCKT4res switch (nfsstat4 status) { 9149 case NFS4ERR_DENIED: 9150 LOCK4denied denied; 9152 Draft Specification NFS version 4 Protocol January 2000 9154 case NFS4_OK: 9155 void; 9156 default: 9157 void; 9158 }; 9160 struct LOCKU4args { 9161 /* CURRENT_FH: file */ 9162 nfs_lock_type4 type; 9163 seqid4 seqid; 9164 stateid4 stateid; 9165 offset4 offset; 9166 length4 length; 9167 }; 9169 union LOCKU4res switch (nfsstat4 status) { 9170 case NFS4_OK: 9171 stateid4 stateid; 9172 default: 9173 void; 9174 }; 9176 /* 9177 * LOOKUP: Lookup filename 9178 */ 9179 struct LOOKUP4args { 9180 /* CURRENT_FH: directory */ 9181 pathname4 path; 9182 }; 9184 struct LOOKUP4res { 9185 /* CURRENT_FH: object */ 9186 nfsstat4 status; 9187 }; 9189 /* 9190 * LOOKUPP: Lookup parent directory 9191 */ 9192 struct LOOKUPP4res { 9193 /* CURRENT_FH: directory */ 9194 nfsstat4 status; 9195 }; 9197 /* 9198 * NVERIFY: Verify attributes different 9199 */ 9200 struct NVERIFY4args { 9201 /* CURRENT_FH: object */ 9203 Draft Specification NFS version 4 Protocol January 2000 9205 bitmap4 attr_request; 9206 fattr4 obj_attributes; 9207 }; 9209 struct NVERIFY4res { 9210 nfsstat4 status; 9211 }; 9213 /* 9214 * Various definitions for OPEN 9215 */ 9216 enum createmode4 { 9217 UNCHECKED4 = 0, 9218 GUARDED4 = 1, 9219 EXCLUSIVE4 = 2 9220 }; 9222 union createhow4 switch (createmode4 mode) { 9223 case UNCHECKED4: 9224 case GUARDED4: 9225 fattr4 createattrs; 9226 case EXCLUSIVE4: 9227 verifier4 createverf; 9228 }; 9230 enum opentype4 { 9231 OPEN4_NOCREATE = 0, 9232 OPEN4_CREATE = 1 9233 }; 9235 union openflag4 switch (opentype4 opentype) { 9236 case OPEN4_CREATE: 9237 createhow4 how; 9238 default: 9239 void; 9240 }; 9242 /* Next definitions used for OPEN delegation */ 9243 enum limit_by4 { 9244 NFS_LIMIT_SIZE = 1, 9245 NFS_LIMIT_BLOCKS = 2 9246 /* others as needed */ 9247 }; 9249 struct nfs_modified_limit4 { 9250 uint32_t num_blocks; 9251 uint32_t bytes_per_block; 9252 }; 9254 Draft Specification NFS version 4 Protocol January 2000 9256 union nfs_space_limit4 switch (limit_by4 limitby) { 9257 /* limit specified as file size */ 9258 case NFS_LIMIT_SIZE: 9259 uint64_t filesize; 9260 /* limit specified by number of blocks */ 9261 case NFS_LIMIT_BLOCKS: 9262 nfs_modified_limit4 mod_blocks; 9263 } ; 9265 /* 9266 * Share Access and Deny constants for open argument 9267 */ 9268 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 9269 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 9270 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 9272 const OPEN4_SHARE_DENY_NONE = 0x00000000; 9273 const OPEN4_SHARE_DENY_READ = 0x00000001; 9274 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 9275 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 9277 enum open_delegation_type4 { 9278 OPEN_DELEGATE_NONE = 0, 9279 OPEN_DELEGATE_READ = 1, 9280 OPEN_DELEGATE_WRITE = 2 9281 }; 9283 enum open_claim_type4 { 9284 CLAIM_NULL = 0, 9285 CLAIM_PREVIOUS = 1, 9286 CLAIM_DELEGATE_CUR = 2, 9287 CLAIM_DELEGATE_PREV = 3 9288 }; 9290 struct open_claim_delegate_cur4 { 9291 pathname4 file; 9292 stateid4 delegate_stateid; 9293 }; 9295 union open_claim4 switch (open_claim_type4 claim) { 9296 /* 9297 * No special rights to file. Ordinary OPEN of the specified file. 9298 */ 9299 case CLAIM_NULL: 9300 /* CURRENT_FH: directory */ 9301 pathname4 file; 9303 /* 9305 Draft Specification NFS version 4 Protocol January 2000 9307 * Right to the file established by an open previous to server 9308 * reboot. File identified by filehandle obtained at that time 9309 * rather than by name. 9310 */ 9311 case CLAIM_PREVIOUS: 9312 /* CURRENT_FH: file being reclaimed */ 9313 uint32_t delegate_type; 9315 /* 9316 * Right to file based on a delegation granted by the server. 9317 * File is specified by name. 9318 */ 9319 case CLAIM_DELEGATE_CUR: 9320 /* CURRENT_FH: directory */ 9321 open_claim_delegate_cur4 delegate_cur_info; 9323 /* Right to file based on a delegation granted to a previous boot 9324 * instance of the client. File is specified by name. 9325 */ 9326 case CLAIM_DELEGATE_PREV: 9327 /* CURRENT_FH: directory */ 9328 pathname4 file_delegate_prev; 9329 }; 9331 /* 9332 * OPEN: Open a file, potentially receiving an open delegation 9333 */ 9334 struct OPEN4args { 9335 open_claim4 claim; 9336 openflag4 openhow; 9337 nfs_lockowner4 owner; 9338 seqid4 seqid; 9339 uint32_t share_access; 9340 uint32_t share_deny; 9341 }; 9343 struct open_read_delegation4 { 9344 stateid4 stateid; /* Stateid for delegation*/ 9345 bool recall; /* Pre-recalled flag for 9346 delegations obtained 9347 by reclaim 9348 (CLAIM_PREVIOUS) */ 9349 nfsace4 permissions; /* Defines users who don't 9350 need an ACCESS call to 9351 open for read */ 9352 }; 9354 struct open_write_delegation4 { 9356 Draft Specification NFS version 4 Protocol January 2000 9358 stateid4 stateid; /* Stateid for delegation 9359 be flushed to the server 9360 on close. */ 9361 bool recall; /* Pre-recalled flag for 9362 delegations obtained 9363 by reclaim 9364 (CLAIM_PREVIOUS) */ 9365 nfs_space_limit4 space_limit; /* Defines condition that 9366 the client must check to 9367 determine whether the 9368 file needs to be flushed 9369 to the server on close. 9370 */ 9371 nfsace4 permissions; /* Defines users who don't 9372 need an ACCESS call as 9373 part of a delegated 9374 open. */ 9375 }; 9377 union open_delegation4 9378 switch (open_delegation_type4 delegation_type) { 9379 case OPEN_DELEGATE_NONE: 9380 void; 9381 case OPEN_DELEGATE_READ: 9382 open_read_delegation4 read; 9383 case OPEN_DELEGATE_WRITE: 9384 open_write_delegation4 write; 9385 }; 9387 /* 9388 * Result flags 9389 */ 9390 /* Mandatory locking is in effect for this file. */ 9391 const OPEN4_RESULT_MLOCK = 0x00000001; 9392 /* Client must confirm open */ 9393 const OPEN4_RESULT_CONFIRM = 0x00000002; 9395 struct OPEN4resok { 9396 stateid4 stateid; /* Stateid for open */ 9397 change_info4 cinfo; /* Directory Change Info */ 9398 uint32_t rflags; /* Result flags */ 9399 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 9400 open_delegation4 delegation; /* Info on any open 9401 delegation */ 9402 }; 9404 union OPEN4res switch (nfsstat4 status) { 9405 case NFS4_OK: 9407 Draft Specification NFS version 4 Protocol January 2000 9409 /* CURRENT_FH: opened file */ 9410 OPEN4resok result; 9411 default: 9412 void; 9413 }; 9415 /* 9416 * OPENATTR: open named attributes directory 9417 */ 9418 struct OPENATTR4res { 9419 /* CURRENT_FH: name attr directory*/ 9420 nfsstat4 status; 9421 }; 9423 /* 9424 * OPEN_CONFIRM: confirm the open 9425 */ 9426 struct OPEN_CONFIRM4args { 9427 /* CURRENT_FH: opened file */ 9428 seqid4 seqid; 9429 verifier4 open_confirm; /* OPEN_CONFIRM verifier */ 9430 }; 9432 struct OPEN_CONFIRM4resok { 9433 stateid4 stateid; 9434 }; 9436 union OPEN_CONFIRM4res switch (nfsstat4 status) { 9437 case NFS4_OK: 9438 OPEN_CONFIRM4resok resok4; 9439 default: 9440 void; 9441 }; 9443 /* 9444 * OPEN_DOWNGRADE: downgrade the access/deny for a file 9445 */ 9446 struct OPEN_DOWNGRADE4args { 9447 /* CURRENT_FH: opened file */ 9448 stateid4 stateid; 9449 seqid4 seqid; 9450 uint32_t share_access; 9451 uint32_t share_deny; 9452 }; 9454 struct OPEN_DOWNGRADE4resok { 9455 stateid4 stateid; 9456 }; 9458 Draft Specification NFS version 4 Protocol January 2000 9460 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 9461 case NFS4_OK: 9462 OPEN_DOWNGRADE4resok resok4; 9463 default: 9464 void; 9465 }; 9467 /* 9468 * PUTFH: Set current filehandle 9469 */ 9470 struct PUTFH4args { 9471 nfs_fh4 object; 9472 }; 9474 struct PUTFH4res { 9475 /* CURRENT_FH: */ 9476 nfsstat4 status; 9477 }; 9479 /* 9480 * PUTPUBFH: Set public filehandle 9481 */ 9482 struct PUTPUBFH4res { 9483 /* CURRENT_FH: public fh */ 9484 nfsstat4 status; 9485 }; 9487 /* 9488 * PUTROOTFH: Set root filehandle 9489 */ 9490 struct PUTROOTFH4res { 9491 /* CURRENT_FH: root fh */ 9492 nfsstat4 status; 9493 }; 9495 /* 9496 * READ: Read from file 9497 */ 9498 struct READ4args { 9499 /* CURRENT_FH: file */ 9500 stateid4 stateid; 9501 offset4 offset; 9502 count4 count; 9503 }; 9505 struct READ4resok { 9506 bool eof; 9507 opaque data<>; 9509 Draft Specification NFS version 4 Protocol January 2000 9511 }; 9513 union READ4res switch (nfsstat4 status) { 9514 case NFS4_OK: 9515 READ4resok resok4; 9516 default: 9517 void; 9518 }; 9520 /* 9521 * READDIR: Read directory 9522 */ 9523 struct READDIR4args { 9524 /* CURRENT_FH: directory */ 9525 nfs_cookie4 cookie; 9526 verifier4 cookieverf; 9527 count4 dircount; 9528 count4 maxcount; 9529 bitmap4 attr_request; 9530 }; 9532 struct entry4 { 9533 nfs_cookie4 cookie; 9534 component4 name; 9535 fattr4 attrs; 9536 entry4 *nextentry; 9537 }; 9539 struct dirlist4 { 9540 entry4 *entries; 9541 bool eof; 9542 }; 9544 struct READDIR4resok { 9545 verifier4 cookieverf; 9546 dirlist4 reply; 9547 }; 9549 union READDIR4res switch (nfsstat4 status) { 9550 case NFS4_OK: 9551 READDIR4resok resok4; 9552 default: 9553 void; 9554 }; 9556 /* 9558 Draft Specification NFS version 4 Protocol January 2000 9560 * READLINK: Read symbolic link 9561 */ 9562 struct READLINK4resok { 9563 linktext4 link; 9564 }; 9566 union READLINK4res switch (nfsstat4 status) { 9567 case NFS4_OK: 9568 READLINK4resok resok4; 9569 default: 9570 void; 9571 }; 9573 /* 9574 * REMOVE: Remove filesystem object 9575 */ 9576 struct REMOVE4args { 9577 /* CURRENT_FH: directory */ 9578 component4 target; 9579 }; 9581 struct REMOVE4resok { 9582 change_info4 cinfo; 9583 }; 9585 union REMOVE4res switch (nfsstat4 status) { 9586 case NFS4_OK: 9587 REMOVE4resok resok4; 9588 default: 9589 void; 9590 }; 9592 /* 9593 * RENAME: Rename directory entry 9594 */ 9595 struct RENAME4args { 9596 /* SAVED_FH: source directory */ 9597 component4 oldname; 9598 /* CURRENT_FH: target directory */ 9599 component4 newname; 9600 }; 9602 struct RENAME4resok { 9603 change_info4 source_cinfo; 9604 change_info4 target_cinfo; 9605 }; 9607 union RENAME4res switch (nfsstat4 status) { 9609 Draft Specification NFS version 4 Protocol January 2000 9611 case NFS4_OK: 9612 RENAME4resok resok4; 9613 default: 9614 void; 9615 }; 9617 /* 9618 * RENEW: Renew a Lease 9619 */ 9620 struct RENEW4args { 9621 stateid4 stateid; 9622 }; 9624 struct RENEW4res { 9625 nfsstat4 status; 9626 }; 9628 /* 9629 * RESTOREFH: Restore saved filehandle 9630 */ 9632 struct RESTOREFH4res { 9633 /* CURRENT_FH: value of saved fh */ 9634 nfsstat4 status; 9635 }; 9637 /* 9638 * SAVEFH: Save current filehandle 9639 */ 9640 struct SAVEFH4res { 9641 /* SAVED_FH: value of current fh */ 9642 nfsstat4 status; 9643 }; 9645 /* 9646 * SECINFO: Obtain Available Security Mechanisms 9647 */ 9648 struct SECINFO4args { 9649 /* CURRENT_FH: */ 9650 component4 name; 9651 }; 9653 /* 9654 * From RFC 2203 9655 */ 9656 enum rpc_gss_svc_t { 9657 RPC_GSS_SVC_NONE = 1, 9658 RPC_GSS_SVC_INTEGRITY = 2, 9660 Draft Specification NFS version 4 Protocol January 2000 9662 RPC_GSS_SVC_PRIVACY = 3 9663 }; 9665 struct rpcsec_gss_info { 9666 sec_oid4 oid; 9667 qop4 qop; 9668 rpc_gss_svc_t service; 9669 }; 9671 struct secinfo4 { 9672 uint32_t flavor; 9673 /* null for AUTH_SYS, AUTH_NONE; 9674 contains rpcsec_gss_info for 9675 RPCSEC_GSS. */ 9676 opaque flavor_info<>; 9677 }; 9679 typedef secinfo4 SECINFO4resok<>; 9681 union SECINFO4res switch (nfsstat4 status) { 9682 case NFS4_OK: 9683 SECINFO4resok resok4; 9684 default: 9685 void; 9686 }; 9688 /* 9689 * SETATTR: Set attributes 9690 */ 9691 struct SETATTR4args { 9692 /* CURRENT_FH: target object */ 9693 stateid4 stateid; 9694 fattr4 obj_attributes; 9695 }; 9697 struct SETATTR4res { 9698 nfsstat4 status; 9699 bitmap4 attrsset; 9700 }; 9702 /* 9703 * SETCLIENTID 9704 */ 9705 struct SETCLIENTID4args { 9706 nfs_client_id4 client; 9707 cb_client4 callback; 9708 }; 9710 Draft Specification NFS version 4 Protocol January 2000 9712 struct SETCLIENTID4resok { 9713 clientid4 clientid; 9714 verifier4 setclientid_confirm; 9715 }; 9717 union SETCLIENTID4res switch (nfsstat4 status) { 9718 case NFS4_OK: 9719 SETCLIENTID4resok resok4; 9720 case NFS4ERR_CLID_INUSE: 9721 clientaddr4 client_using; 9722 default: 9723 void; 9724 }; 9726 struct SETCLIENTID_CONFIRM4args { 9727 verifier4 setclientid_confirm; 9728 }; 9730 struct SETCLIENTID_CONFIRM4res { 9731 nfsstat4 status; 9732 }; 9734 /* 9735 * VERIFY: Verify attributes same 9736 */ 9737 struct VERIFY4args { 9738 /* CURRENT_FH: object */ 9739 bitmap4 attr_request; 9740 fattr4 obj_attributes; 9741 }; 9743 struct VERIFY4res { 9744 nfsstat4 status; 9745 }; 9747 /* 9748 * WRITE: Write to file 9749 */ 9750 enum stable_how4 { 9751 UNSTABLE4 = 0, 9752 DATA_SYNC4 = 1, 9753 FILE_SYNC4 = 2 9754 }; 9756 struct WRITE4args { 9757 /* CURRENT_FH: file */ 9758 stateid4 stateid; 9759 offset4 offset; 9761 Draft Specification NFS version 4 Protocol January 2000 9763 stable_how4 stable; 9764 opaque data<>; 9765 }; 9767 struct WRITE4resok { 9768 count4 count; 9769 stable_how4 committed; 9770 verifier4 writeverf; 9771 }; 9773 union WRITE4res switch (nfsstat4 status) { 9774 case NFS4_OK: 9775 WRITE4resok resok4; 9776 default: 9777 void; 9778 }; 9780 /* 9781 * Operation arrays 9782 */ 9784 enum nfs_opnum4 { 9785 OP_ACCESS = 3, 9786 OP_CLOSE = 4, 9787 OP_COMMIT = 5, 9788 OP_CREATE = 6, 9789 OP_DELEGPURGE = 7, 9790 OP_DELEGRETURN = 8, 9791 OP_GETATTR = 9, 9792 OP_GETFH = 10, 9793 OP_LINK = 11, 9794 OP_LOCK = 12, 9795 OP_LOCKT = 13, 9796 OP_LOCKU = 14, 9797 OP_LOOKUP = 15, 9798 OP_LOOKUPP = 16, 9799 OP_NVERIFY = 17, 9800 OP_OPEN = 18, 9801 OP_OPENATTR = 19, 9802 OP_OPEN_CONFIRM = 20, 9803 OP_OPEN_DOWNGRADE = 21, 9804 OP_PUTFH = 22, 9805 OP_PUTPUBFH = 23, 9806 OP_PUTROOTFH = 24, 9807 OP_READ = 25, 9808 OP_READDIR = 26, 9809 OP_READLINK = 27, 9810 OP_REMOVE = 28, 9812 Draft Specification NFS version 4 Protocol January 2000 9814 OP_RENAME = 29, 9815 OP_RENEW = 30, 9816 OP_RESTOREFH = 31, 9817 OP_SAVEFH = 32, 9818 OP_SECINFO = 33, 9819 OP_SETATTR = 34, 9820 OP_SETCLIENTID = 35, 9821 OP_SETCLIENTID_CONFIRM = 36, 9822 OP_VERIFY = 37, 9823 OP_WRITE = 38 9824 }; 9826 union nfs_argop4 switch (nfs_opnum4 argop) { 9827 case OP_ACCESS: ACCESS4args opaccess; 9828 case OP_CLOSE: CLOSE4args opclose; 9829 case OP_COMMIT: COMMIT4args opcommit; 9830 case OP_CREATE: CREATE4args opcreate; 9831 case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; 9832 case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; 9833 case OP_GETATTR: GETATTR4args opgetattr; 9834 case OP_GETFH: void; 9835 case OP_LINK: LINK4args oplink; 9836 case OP_LOCK: LOCK4args oplock; 9837 case OP_LOCKT: LOCK4args oplockt; 9838 case OP_LOCKU: LOCK4args oplocku; 9839 case OP_LOOKUP: LOOKUP4args oplookup; 9840 case OP_LOOKUPP: void; 9841 case OP_NVERIFY: NVERIFY4args opnverify; 9842 case OP_OPEN: OPEN4args opopen; 9843 case OP_OPENATTR: void; 9844 case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; 9845 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4args opopen_downgrade; 9846 case OP_PUTFH: PUTFH4args opputfh; 9847 case OP_PUTPUBFH: void; 9848 case OP_PUTROOTFH: void; 9849 case OP_READ: READ4args opread; 9850 case OP_READDIR: READDIR4args opreaddir; 9851 case OP_READLINK: void; 9852 case OP_REMOVE: REMOVE4args opremove; 9853 case OP_RENAME: RENAME4args oprename; 9854 case OP_RENEW: RENEW4args oprenew; 9855 case OP_RESTOREFH: void; 9856 case OP_SAVEFH: void; 9857 case OP_SECINFO: SECINFO4args opsecinfo; 9858 case OP_SETATTR: SETATTR4args opsetattr; 9859 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 9860 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args 9861 opsetclientid_confirm; 9863 Draft Specification NFS version 4 Protocol January 2000 9865 case OP_VERIFY: VERIFY4args opverify; 9866 case OP_WRITE: WRITE4args opwrite; 9867 }; 9869 union nfs_resop4 switch (nfs_opnum4 resop){ 9870 case OP_ACCESS: ACCESS4res opaccess; 9871 case OP_CLOSE: CLOSE4res opclose; 9872 case OP_COMMIT: COMMIT4res opcommit; 9873 case OP_CREATE: CREATE4res opcreate; 9874 case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; 9875 case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; 9876 case OP_GETATTR: GETATTR4res opgetattr; 9877 case OP_GETFH: GETFH4res opgetfh; 9878 case OP_LINK: LINK4res oplink; 9879 case OP_LOCK: LOCK4res oplock; 9880 case OP_LOCKT: LOCKT4res oplockt; 9881 case OP_LOCKU: LOCKU4res oplocku; 9882 case OP_LOOKUP: LOOKUP4res oplookup; 9883 case OP_LOOKUPP: LOOKUPP4res oplookupp; 9884 case OP_NVERIFY: NVERIFY4res opnverify; 9885 case OP_OPEN: OPEN4res opopen; 9886 case OP_OPENATTR: OPENATTR4res opopenattr; 9887 case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; 9888 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4res opopen_downgrade; 9889 case OP_PUTFH: PUTFH4res opputfh; 9890 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 9891 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 9892 case OP_READ: READ4res opread; 9893 case OP_READDIR: READDIR4res opreaddir; 9894 case OP_READLINK: READLINK4res opreadlink; 9895 case OP_REMOVE: REMOVE4res opremove; 9896 case OP_RENAME: RENAME4res oprename; 9897 case OP_RENEW: RENEW4res oprenew; 9898 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 9899 case OP_SAVEFH: SAVEFH4res opsavefh; 9900 case OP_SECINFO: SECINFO4res opsecinfo; 9901 case OP_SETATTR: SETATTR4res opsetattr; 9902 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 9903 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4res 9904 opsetclientid_confirm; 9905 case OP_VERIFY: VERIFY4res opverify; 9906 case OP_WRITE: WRITE4res opwrite; 9907 }; 9909 struct COMPOUND4args { 9910 utf8string tag; 9911 uint32_t minorversion; 9912 nfs_argop4 argarray<>; 9914 Draft Specification NFS version 4 Protocol January 2000 9916 }; 9918 struct COMPOUND4res { 9919 nfsstat4 status; 9920 utf8string tag; 9921 nfs_resop4 resarray<>; 9922 }; 9924 /* 9925 * Remote file service routines 9926 */ 9927 program NFS4_PROGRAM { 9928 version NFS_V4 { 9929 void 9930 NFSPROC4_NULL(void) = 0; 9932 COMPOUND4res 9933 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 9935 } = 4; 9936 } = 100003; 9938 /* 9939 * NFS4 Callback Procedure Definitions and Program 9940 */ 9942 /* 9943 * CB_GETATTR: Get Current Attributes 9944 */ 9945 struct CB_GETATTR4args { 9946 nfs_fh4 fh; 9947 bitmap4 attr_request; 9948 }; 9950 struct CB_GETATTR4resok { 9951 fattr4 obj_attributes; 9952 }; 9954 union CB_GETATTR4res switch (nfsstat4 status) { 9955 case NFS4_OK: 9956 CB_GETATTR4resok resok4; 9957 default: 9958 void; 9959 }; 9961 /* 9963 Draft Specification NFS version 4 Protocol January 2000 9965 * CB_RECALL: Recall an Open Delegation 9966 */ 9967 struct CB_RECALL4args { 9968 stateid4 stateid; 9969 bool truncate; 9970 nfs_fh4 fh; 9971 }; 9973 struct CB_RECALL4res { 9974 nfsstat4 status; 9975 }; 9977 /* 9978 * Various definitions for CB_COMPOUND 9979 */ 9980 enum nfs_cb_opnum4 { 9981 OP_CB_GETATTR = 3, 9982 OP_CB_RECALL = 4 9983 }; 9985 union nfs_cb_argop4 switch (unsigned argop) { 9986 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 9987 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 9988 }; 9990 union nfs_cb_resop4 switch (unsigned resop){ 9991 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 9992 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 9993 }; 9995 struct CB_COMPOUND4args { 9996 utf8string tag; 9997 uint32_t minorversion; 9998 nfs_cb_argop4 argarray<>; 9999 }; 10001 struct CB_COMPOUND4res { 10002 nfsstat4 status; 10003 utf8string tag; 10004 nfs_cb_resop4 resarray<>; 10005 }; 10007 /* 10008 * Program number is in the transient range since the client 10009 * will assign the exact transient program number and provide 10010 * that to the server via the SETCLIENTID operation. 10011 */ 10013 Draft Specification NFS version 4 Protocol January 2000 10015 program NFS4_CALLBACK { 10016 version NFS_CB { 10017 void 10018 CB_NULL(void) = 0; 10019 CB_COMPOUND4res 10020 CB_COMPOUND(CB_COMPOUND4args) = 1; 10021 } = 1; 10022 } = 40000000; 10024 Draft Specification NFS version 4 Protocol January 2000 10026 19. Bibliography 10028 [Gray] 10029 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 10030 for Distributed File Cache Consistency," Proceedings of the Twelfth 10031 Symposium on Operating Systems Principles, p. 202-210, December 1989. 10033 [Juszczak] 10034 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 10035 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 10036 CA, June 1990, pages 53-63. Describes reply cache implementation 10037 that avoids work in the server by handling duplicate requests. More 10038 important, though listed as a side-effect, the reply cache aids in 10039 the avoidance of destructive non-idempotent operation re-application 10040 -- improving correctness. 10042 [Kazar] 10043 Kazar, Michael Leon, "Synchronization and Caching Issues in the 10044 Andrew File System," USENIX Conference Proceedings, USENIX 10045 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 10046 description of the cache consistency scheme in AFS. Contrasted with 10047 other distributed file systems. 10049 [Macklem] 10050 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 10051 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 10052 Association, Berkeley, CA, January 1991. Describes performance work 10053 in tuning the 4.3BSD Reno NFS implementation. Describes performance 10054 improvement (reduced CPU loading) through elimination of data copies. 10056 [Mogul] 10057 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 10058 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 10059 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 10060 lease-based scheme for recovering state of consistency protocol. 10062 [Nowicki] 10063 Nowicki, Bill, "Transport Issues in the Network File System," ACM 10064 SIGCOMM newsletter Computer Communication Review, April 1989. A 10065 brief description of the basis for the dynamic retransmission work. 10067 Draft Specification NFS version 4 Protocol January 2000 10069 [Pawlowski] 10070 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 10071 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 10072 Conf. Proc., (1989) Description of an NFS server implementation for 10073 IBM's MVS operating system. 10075 [RFC1094] 10076 Sun Microsystems, Inc., "NFS: Network File System Protocol 10077 Specification", RFC1094, March 1989. 10079 http://www.ietf.org/rfc/rfc1094.txt 10081 [RFC1345] 10082 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 10083 Rationel Almen Planlaegning, June 1992. 10085 http://www.ietf.org/rfc/rfc1345.txt 10087 [RFC1700] 10088 Reynolds, J., Postel, J., "Assigned Numbers", RFC1700, ISI, October 10089 1994 10091 http://www.ietf.org/rfc/rfc1700.txt 10093 [RFC1813] 10094 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 10095 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 10097 http://www.ietf.org/rfc/rfc1813.txt 10099 [RFC1831] 10100 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 10101 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 10103 http://www.ietf.org/rfc/rfc1831.txt 10105 [RFC1832] 10106 Srinivasan, R., "XDR: External Data Representation Standard", 10107 RFC1832, Sun Microsystems, Inc., August 1995. 10109 http://www.ietf.org/rfc/rfc1832.txt 10111 Draft Specification NFS version 4 Protocol January 2000 10113 [RFC1833] 10114 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 10115 Sun Microsystems, Inc., August 1995. 10117 http://www.ietf.org/rfc/rfc1833.txt 10119 [RFC2025] 10120 Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", RFC2025, 10121 Bell-Northern Research, October 1996. 10123 http://www.ietf.org/rfc/rfc2026.txt 10125 [RFC2054] 10126 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 10127 Microsystems, Inc., October 1996 10129 http://www.ietf.org/rfc/rfc2054.txt 10131 [RFC2055] 10132 Callaghan, B., "WebNFS Server Specification", RFC2055, Sun 10133 Microsystems, Inc., October 1996 10135 http://www.ietf.org/rfc/rfc2055.txt 10137 [RFC2078] 10138 Linn, J., "Generic Security Service Application Program Interface, 10139 Version 2", RFC2078, OpenVision Technologies, January 1997. 10141 http://www.ietf.org/rfc/rfc2078.txt 10143 [RFC2152] 10144 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 10145 RFC2152, Apple Computer, Inc., May 1997 10147 http://www.ietf.org/rfc/rfc2152.txt 10149 [RFC2203] 10150 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 10151 RFC2203, Sun Microsystems, Inc., August 1995. 10153 http://www.ietf.org/rfc/rfc2203.txt 10155 Draft Specification NFS version 4 Protocol January 2000 10157 [RFC2277] 10158 Alvestrand, H., "IETF Policy on Character Sets and Languages", 10159 RFC2277, UNINETT, January 1998. 10161 http://www.ietf.org/rfc/rfc2277.txt 10163 [RFC2279] 10164 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 10165 Alis Technologies, January 1998. 10167 http://www.ietf.org/rfc/rfc2279.txt 10169 [RFC2623] 10170 Eisler, M., "NFS Version 2 and Version 3 Security Issues and the NFS 10171 Protocol's Use of RPCSEC_GSS and Kerberos V5", RFC2623, Sun 10172 Microsystems, June 1999 10174 http://www.ietf.org/rfc/rfc2623.txt 10176 [RFC2624] 10177 Shepler, S., "NFS Version 4 Design Considerations", RFC2624, Sun 10178 Microsystems, June 1999 10180 http://www.ietf.org/rfc/rfc2624.txt 10182 [RFCXXXX] 10183 Eisler, M., "LIPKEY - A Low Infrastructure Public Key Mechanism Using 10184 SPKM", RFCXXXX, Sun Microsystems, December 1999 10186 http://www.ietf.org/internet-drafts/draft-ietf-cat-lipkey-03.txt 10188 [Sandberg] 10189 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 10190 and Implementation of the Sun Network Filesystem," USENIX Conference 10191 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 10192 basic paper describing the SunOS implementation of the NFS version 2 10193 protocol, and discusses the goals, protocol specification and trade- 10194 offs. 10196 [Srinivasan] 10197 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 10198 Performance of Cache Consistency Protocols", WRL Research Report 10200 Draft Specification NFS version 4 Protocol January 2000 10202 89/5, Digital Equipment Corporation Western Research Laboratory, 100 10203 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 10204 the effect of applying a Sprite-like consistency protocol applied to 10205 standard NFS. The issues of recovery in a stateful environment are 10206 covered in [Mogul]. 10208 [Unicode1] 10209 The Unicode Consortium, "The Unicode Standard, Version 3.0", 10210 Addison-Wesley Developers Press, Reading, MA, 2000. ISBN 0-201- 10211 61633-5. 10213 More information available at: http://www.unicode.org/ 10215 [Unicode2] 10216 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 10217 700519, San Jose, CA 95710-0519 USA, September 1999 10219 http://www.unicode.org/unicode/standard/unsupported.html 10221 [XNFS] 10222 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 10223 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 10224 1-85912-184-5, February 1998. 10226 HTML version available: http://www.opengroup.org 10228 Draft Specification NFS version 4 Protocol January 2000 10230 20. Authors and Contributors 10232 General feedback related to this document should be directed to: 10234 nfsv4-wg@sunroof.eng.sun.com 10236 or the editor. 10238 20.1. Editor's Address 10240 Spencer Shepler 10241 Sun Microsystems, Inc. 10242 7808 Moonflower Drive 10243 Austin, Texas 78750 10245 Phone: +1 512-349-9376 10246 E-mail: shepler@eng.sun.com 10248 20.2. Authors' Addresses 10250 Carl Beame 10251 Hummingbird Communications Ltd. 10253 E-mail: beame@bws.com 10255 Brent Callaghan 10256 Sun Microsystems, Inc. 10257 901 San Antonio Road 10258 Palo Alto, CA 94303 10260 Phone: +1 650-786-5067 10261 E-mail: brent.callaghan@eng.sun.com 10263 Mike Eisler 10264 Sun Microsystems, Inc. 10265 5565 Wilson Road 10266 Colorado Springs, CO 80919 10268 Phone: +1 719-599-9026 10269 E-mail: mre@eng.sun.com 10271 Dave Noveck 10272 Network Appliance 10273 495 East Java Drive 10274 Sunnyvale, CA 94089 10276 Draft Specification NFS version 4 Protocol January 2000 10278 Phone: +1 781-861-9291 10279 E-mail: dave.noveck@netapp.com 10281 David Robinson 10282 Sun Microsystems, Inc. 10283 901 San Antonio Road 10284 Palo Alto, CA 94303 10286 Phone: +1 650-786-5088 10287 E-mail: david.robinson@eng.sun.com 10289 Robert Thurlow 10290 Sun Microsystems, Inc. 10291 901 San Antonio Road 10292 Palo Alto, CA 94303 10294 Phone: +1 650-786-5096 10295 E-mail: robert.thurlow@eng.sun.com 10297 Draft Specification NFS version 4 Protocol January 2000 10299 21. Full Copyright Statement 10301 "Copyright (C) The Internet Society (2000). All Rights Reserved. 10303 This document and translations of it may be copied and furnished to 10304 others, and derivative works that comment on or otherwise explain it 10305 or assist in its implementation may be prepared, copied, published 10306 and distributed, in whole or in part, without restriction of any 10307 kind, provided that the above copyright notice and this paragraph are 10308 included on all such copies and derivative works. However, this 10309 document itself may not be modified in any way, such as by removing 10310 the copyright notice or references to the Internet Society or other 10311 Internet organizations, except as needed for the purpose of 10312 developing Internet standards in which case the procedures for 10313 copyrights defined in the Internet Standards process must be 10314 followed, or as required to translate it into languages other than 10315 English. 10317 The limited permissions granted above are perpetual and will not be 10318 revoked by the Internet Society or its successors or assigns. 10320 This document and the information contained herein is provided on an 10321 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 10322 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 10323 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 10324 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 10325 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."