idnits 2.17.1 draft-ietf-nfsv4-rfc3010bis-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard 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 613 has weird spacing: '...ned int uin...' == Line 617 has weird spacing: '...d hyper uint6...' == Line 679 has weird spacing: '...8string typ...' == Line 764 has weird spacing: '...8string ser...' == Line 829 has weird spacing: '...ned int cb_pr...' == (38 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 'SHOULD not' in this paragraph: The filehandle in the NFS protocol is a per server unique identifier for a file system object. The contents of the filehandle are opaque to the client. Therefore, the server is responsible for translating the filehandle to an internal representation of the file system object. Since the filehandle is the client's reference to an object and the client may cache this reference, the server SHOULD not reuse a filehandle for another file system object. If the server needs to reuse a filehandle value, the time elapsed before reuse SHOULD be large enough such that it is unlikely the client has a cached copy of the reused filehandle value. Note that a client may cache a filehandle for a very long time. For example, a client may cache NFS data to local storage as a method to expand its effective cache size and as a means to survive client restarts. Therefore, the lifetime of a cached filehandle may be extended. == 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: 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 (November 2001) is 8192 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 10609 looks like a reference -- Missing reference section? 'RFC1813' on line 10627 looks like a reference -- Missing reference section? 'RFC1831' on line 10633 looks like a reference -- Missing reference section? 'RFC1832' on line 10639 looks like a reference -- Missing reference section? 'RFC2203' on line 10683 looks like a reference -- Missing reference section? 'RFC1964' on line 935 looks like a reference -- Missing reference section? 'RFC2847' on line 10716 looks like a reference -- Missing reference section? 'RFC2078' on line 10671 looks like a reference -- Missing reference section? '12' on line 9398 looks like a reference -- Missing reference section? 'RFC1700' on line 10621 looks like a reference -- Missing reference section? 'RFC1833' on line 10647 looks like a reference -- Missing reference section? 'RFC2581' on line 895 looks like a reference -- Missing reference section? 'Floyd' on line 10552 looks like a reference -- Missing reference section? 'RFC2623' on line 10703 looks like a reference -- Missing reference section? 'RFC2025' on line 10653 looks like a reference -- Missing reference section? 'RFC2054' on line 10659 looks like a reference -- Missing reference section? 'RFC2055' on line 10665 looks like a reference -- Missing reference section? 'RFC2624' on line 10710 looks like a reference -- Missing reference section? 'RFC1345' on line 10615 looks like a reference -- Missing reference section? 'XNFS' on line 10755 looks like a reference -- Missing reference section? '4' on line 2569 looks like a reference -- Missing reference section? 'Juszczak' on line 10567 looks like a reference -- Missing reference section? 'ISO10646' on line 10562 looks like a reference -- Missing reference section? 'RFC2277' on line 10691 looks like a reference -- Missing reference section? 'RFC2279' on line 10697 looks like a reference -- Missing reference section? 'RFC2152' on line 10677 looks like a reference -- Missing reference section? 'Unicode1' on line 10742 looks like a reference -- Missing reference section? 'Unicode2' on line 10749 looks like a reference -- Missing reference section? 'Gray' on line 10557 looks like a reference -- Missing reference section? 'Kazar' on line 10576 looks like a reference -- Missing reference section? 'Macklem' on line 10583 looks like a reference -- Missing reference section? 'Mogul' on line 10740 looks like a reference -- Missing reference section? 'Nowicki' on line 10598 looks like a reference -- Missing reference section? 'Pawlowski' on line 10603 looks like a reference -- Missing reference section? 'Sandberg' on line 10722 looks like a reference -- Missing reference section? 'Srinivasan' on line 10730 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 10 warnings (==), 39 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFS Version 4 Working Group S. Shepler 3 INTERNET-DRAFT Sun Microsystems, Inc. 4 Document: draft-ietf-nfsv4-rfc3010bis-00.txt C. Beame 5 Hummingbird Ltd. 6 B. Callaghan 7 Sun Microsystems, Inc. 8 M. Eisler 9 Zambeel, Inc. 10 D. Noveck 11 Network Appliance, Inc. 12 D. Robinson 13 Sun Microsystems, Inc. 14 R. Thurlow 15 Sun Microsystems, Inc. 16 November 2001 18 NFS version 4 Protocol 20 Status of this Memo 22 This document is an Internet-Draft and is in full conformance with 23 all provisions of Section 10 of RFC2026. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet- Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 Abstract 43 NFS version 4 is a distributed file system protocol which owes 44 heritage to NFS protocol versions 2 [RFC1094] and 3 [RFC1813]. 46 Draft Specification NFS version 4 Protocol November 2001 48 Unlike earlier versions, the NFS version 4 protocol supports 49 traditional file access while integrating support for file locking 50 and the mount protocol. In addition, support for strong security 51 (and its negotiation), compound operations, client caching, and 52 internationalization have been added. Of course, attention has been 53 applied to making NFS version 4 operate well in an Internet 54 environment. 56 Copyright 58 Copyright (C) The Internet Society (2001). All Rights Reserved. 60 Key Words 62 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 63 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 64 document are to be interpreted as described in RFC 2119. 66 Draft Specification NFS version 4 Protocol November 2001 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 71 1.1. Overview of NFS Version 4 Features . . . . . . . . . . . . 7 72 1.1.1. RPC and Security . . . . . . . . . . . . . . . . . . . . 8 73 1.1.2. Procedure and Operation Structure . . . . . . . . . . . 8 74 1.1.3. File System Model . . . . . . . . . . . . . . . . . . . 9 75 1.1.3.1. Filehandle Types . . . . . . . . . . . . . . . . . . . 9 76 1.1.3.2. Attribute Types . . . . . . . . . . . . . . . . . . . 9 77 1.1.3.3. File System Replication and Migration . . . . . . . 10 78 1.1.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . . 10 79 1.1.5. File locking . . . . . . . . . . . . . . . . . . . . . 10 80 1.1.6. Client Caching and Delegation . . . . . . . . . . . . 11 81 1.2. General Definitions . . . . . . . . . . . . . . . . . . 12 82 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . 14 83 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 14 84 2.2. Structured Data Types . . . . . . . . . . . . . . . . . 15 85 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . 20 86 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 20 87 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 20 88 3.2.1. Security mechanisms for NFS version 4 . . . . . . . . 20 89 3.2.1.1. Kerberos V5 as security triple . . . . . . . . . . . 21 90 3.2.1.2. LIPKEY as a security triple . . . . . . . . . . . . 21 91 3.2.1.3. SPKM-3 as a security triple . . . . . . . . . . . . 22 92 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 23 93 3.3.1. Security Error . . . . . . . . . . . . . . . . . . . . 23 94 3.3.2. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 23 95 3.4. Callback RPC Authentication . . . . . . . . . . . . . . 23 96 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . 26 97 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 26 98 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . . 26 99 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . . 27 100 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 27 101 4.2.1. General Properties of a Filehandle . . . . . . . . . . 27 102 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . . 28 103 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 28 104 4.2.4. One Method of Constructing a Volatile Filehandle . . . 30 105 4.3. Client Recovery from Filehandle Expiration . . . . . . . 30 106 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 32 107 5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 33 108 5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 33 109 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 33 110 5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 35 111 5.5. Recommended Attributes - Definitions . . . . . . . . . . 37 112 5.6. Interpreting owner and owner_group . . . . . . . . . . . 41 113 5.7. Character Case Attributes . . . . . . . . . . . . . . . 42 114 5.8. Quota Attributes . . . . . . . . . . . . . . . . . . . . 42 115 5.9. Access Control Lists . . . . . . . . . . . . . . . . . . 43 116 5.9.1. ACE type . . . . . . . . . . . . . . . . . . . . . . . 44 117 5.9.2. ACE flag . . . . . . . . . . . . . . . . . . . . . . . 44 118 5.9.3. ACE Access Mask . . . . . . . . . . . . . . . . . . . 46 119 5.9.4. ACE who . . . . . . . . . . . . . . . . . . . . . . . 47 121 Draft Specification NFS version 4 Protocol November 2001 123 6. File System Migration and Replication . . . . . . . . . . 48 124 6.1. Replication . . . . . . . . . . . . . . . . . . . . . . 48 125 6.2. Migration . . . . . . . . . . . . . . . . . . . . . . . 48 126 6.3. Interpretation of the fs_locations Attribute . . . . . . 49 127 6.4. Filehandle Recovery for Migration or Replication . . . . 50 128 7. NFS Server Name Space . . . . . . . . . . . . . . . . . . 51 129 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 51 130 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 51 131 7.3. Server Pseudo File System . . . . . . . . . . . . . . . 51 132 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 52 133 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 52 134 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 52 135 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 53 136 7.8. Security Policy and Name Space Presentation . . . . . . 53 137 8. File Locking and Share Reservations . . . . . . . . . . . 54 138 8.1. Locking . . . . . . . . . . . . . . . . . . . . . . . . 54 139 8.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 54 140 8.1.2. Server Release of Clientid . . . . . . . . . . . . . . 56 141 8.1.3. nfs_lockowner and stateid Definition . . . . . . . . . 57 142 8.1.4. Use of the stateid . . . . . . . . . . . . . . . . . . 58 143 8.1.5. Sequencing of Lock Requests . . . . . . . . . . . . . 58 144 8.1.6. Recovery from Replayed Requests . . . . . . . . . . . 59 145 8.1.7. Releasing nfs_lockowner State . . . . . . . . . . . . 59 146 8.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 60 147 8.3. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 61 148 8.4. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 61 149 8.5. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 62 150 8.5.1. Client Failure and Recovery . . . . . . . . . . . . . 62 151 8.5.2. Server Failure and Recovery . . . . . . . . . . . . . 63 152 8.5.3. Network Partitions and Recovery . . . . . . . . . . . 64 153 8.6. Recovery from a Lock Request Timeout or Abort . . . . . 65 154 8.7. Server Revocation of Locks . . . . . . . . . . . . . . . 66 155 8.8. Share Reservations . . . . . . . . . . . . . . . . . . . 67 156 8.9. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 68 157 8.10. Open Upgrade and Downgrade . . . . . . . . . . . . . . 68 158 8.11. Short and Long Leases . . . . . . . . . . . . . . . . . 69 159 8.12. Clocks and Calculating Lease Expiration . . . . . . . . 69 160 8.13. Migration, Replication and State . . . . . . . . . . . 70 161 8.13.1. Migration and State . . . . . . . . . . . . . . . . . 70 162 8.13.2. Replication and State . . . . . . . . . . . . . . . . 70 163 8.13.3. Notification of Migrated Lease . . . . . . . . . . . 71 164 9. Client-Side Caching . . . . . . . . . . . . . . . . . . . 72 165 9.1. Performance Challenges for Client-Side Caching . . . . . 72 166 9.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 73 167 9.2.1. Delegation Recovery . . . . . . . . . . . . . . . . . 74 168 9.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 76 169 9.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . . 76 170 9.3.2. Data Caching and File Locking . . . . . . . . . . . . 77 171 9.3.3. Data Caching and Mandatory File Locking . . . . . . . 78 172 9.3.4. Data Caching and File Identity . . . . . . . . . . . . 79 173 9.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 80 174 9.4.1. Open Delegation and Data Caching . . . . . . . . . . . 82 176 Draft Specification NFS version 4 Protocol November 2001 178 9.4.2. Open Delegation and File Locks . . . . . . . . . . . . 83 179 9.4.3. Recall of Open Delegation . . . . . . . . . . . . . . 83 180 9.4.4. Delegation Revocation . . . . . . . . . . . . . . . . 85 181 9.5. Data Caching and Revocation . . . . . . . . . . . . . . 85 182 9.5.1. Revocation Recovery for Write Open Delegation . . . . 86 183 9.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 87 184 9.7. Name Caching . . . . . . . . . . . . . . . . . . . . . . 88 185 9.8. Directory Caching . . . . . . . . . . . . . . . . . . . 89 186 10. Minor Versioning . . . . . . . . . . . . . . . . . . . . 91 187 11. Internationalization . . . . . . . . . . . . . . . . . . 94 188 11.1. Universal Versus Local Character Sets . . . . . . . . . 94 189 11.2. Overview of Universal Character Set Standards . . . . . 95 190 11.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 96 191 11.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 96 192 11.5. Normalization . . . . . . . . . . . . . . . . . . . . . 97 193 12. Error Definitions . . . . . . . . . . . . . . . . . . . . 98 194 13. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 103 195 13.1. Compound Procedure . . . . . . . . . . . . . . . . . . 103 196 13.2. Evaluation of a Compound Request . . . . . . . . . . . 103 197 13.3. Synchronous Modifying Operations . . . . . . . . . . . 104 198 13.4. Operation Values . . . . . . . . . . . . . . . . . . . 105 199 14. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 106 200 14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 106 201 14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 107 202 14.2.1. Operation 3: ACCESS - Check Access Rights . . . . . . 110 203 14.2.2. Operation 4: CLOSE - Close File . . . . . . . . . . . 113 204 14.2.3. Operation 5: COMMIT - Commit Cached Data . . . . . . 115 205 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 118 206 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 207 Recovery . . . . . . . . . . . . . . . . . . . . . . 120 208 14.2.6. Operation 8: DELEGRETURN - Return Delegation . . . . 121 209 14.2.7. Operation 9: GETATTR - Get Attributes . . . . . . . . 122 210 14.2.8. Operation 10: GETFH - Get Current Filehandle . . . . 124 211 14.2.9. Operation 11: LINK - Create Link to a File . . . . . 126 212 14.2.10. Operation 12: LOCK - Create Lock . . . . . . . . . . 128 213 14.2.11. Operation 13: LOCKT - Test For Lock . . . . . . . . 130 214 14.2.12. Operation 14: LOCKU - Unlock File . . . . . . . . . 132 215 14.2.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . 134 216 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory . . 137 217 14.2.15. Operation 17: NVERIFY - Verify Difference in 218 Attributes . . . . . . . . . . . . . . . . . . . . . 139 219 14.2.16. Operation 18: OPEN - Open a Regular File . . . . . . 141 220 14.2.17. Operation 19: OPENATTR - Open Named Attribute 221 Directory . . . . . . . . . . . . . . . . . . . . . 150 222 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . 152 223 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access155 224 14.2.20. Operation 22: PUTFH - Set Current Filehandle . . . . 157 225 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle . . . 158 226 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle . . . 159 227 14.2.23. Operation 25: READ - Read from File . . . . . . . . 160 228 14.2.24. Operation 26: READDIR - Read Directory . . . . . . . 163 229 14.2.25. Operation 27: READLINK - Read Symbolic Link . . . . 167 231 Draft Specification NFS version 4 Protocol November 2001 233 14.2.26. Operation 28: REMOVE - Remove Filesystem Object . . 169 234 14.2.27. Operation 29: RENAME - Rename Directory Entry . . . 171 235 14.2.28. Operation 30: RENEW - Renew a Lease . . . . . . . . 174 236 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle . 175 237 14.2.30. Operation 32: SAVEFH - Save Current Filehandle . . . 177 238 14.2.31. Operation 33: SECINFO - Obtain Available Security . 178 239 14.2.32. Operation 34: SETATTR - Set Attributes . . . . . . . 180 240 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid . . . 182 241 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 184 242 14.2.35. Operation 37: VERIFY - Verify Same Attributes . . . 185 243 14.2.36. Operation 38: WRITE - Write to File . . . . . . . . 187 244 15. NFS Version 4 Callback Procedures . . . . . . . . . . . . 191 245 15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 191 246 15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 192 247 15.2.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . 194 248 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation . 195 249 16. Security Considerations . . . . . . . . . . . . . . . . . 197 250 17. IANA Considerations . . . . . . . . . . . . . . . . . . . 198 251 17.1. Named Attribute Definition . . . . . . . . . . . . . . 198 252 18. RPC definition file . . . . . . . . . . . . . . . . . . . 199 253 19. Bibliography . . . . . . . . . . . . . . . . . . . . . . 229 254 20. Authors . . . . . . . . . . . . . . . . . . . . . . . . . 234 255 20.1. Editor's Address . . . . . . . . . . . . . . . . . . . 234 256 20.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 234 257 20.3. Acknowledgements . . . . . . . . . . . . . . . . . . . 235 258 21. Full Copyright Statement . . . . . . . . . . . . . . . . 236 260 Draft Specification NFS version 4 Protocol November 2001 262 1. Introduction 264 The NFS version 4 protocol is a further revision of the NFS protocol 265 defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains 266 the essential characteristics of previous versions: design for easy 267 recovery, independent of transport protocols, operating systems and 268 filesystems, simplicity, and good performance. The NFS version 4 269 revision has the following goals: 271 o Improved access and good performance on the Internet. 273 The protocol is designed to transit firewalls easily, perform 274 well where latency is high and bandwidth is low, and scale to 275 very large numbers of clients per server. 277 o Strong security with negotiation built into the protocol. 279 The protocol builds on the work of the ONCRPC working group in 280 supporting the RPCSEC_GSS protocol. Additionally, the NFS 281 version 4 protocol provides a mechanism to allow clients and 282 servers the ability to negotiate security and require clients 283 and servers to support a minimal set of security schemes. 285 o Good cross-platform interoperability. 287 The protocol features a file system model that provides a 288 useful, common set of features that does not unduly favor one 289 file system or operating system over another. 291 o Designed for protocol extensions. 293 The protocol is designed to accept standard extensions that do 294 not compromise backward compatibility. 296 1.1. Overview of NFS Version 4 Features 298 To provide a reasonable context for the reader, the major features of 299 NFS version 4 protocol will be reviewed in brief. This will be done 300 to provide an appropriate context for both the reader who is familiar 301 with the previous versions of the NFS protocol and the reader that is 302 new to the NFS protocols. For the reader new to the NFS protocols, 303 there is still a fundamental knowledge that is expected. The reader 304 should be familiar with the XDR and RPC protocols as described in 305 [RFC1831] and [RFC1832]. A basic knowledge of file systems and 306 distributed file systems is expected as well. 308 Draft Specification NFS version 4 Protocol November 2001 310 1.1.1. RPC and Security 312 As with previous versions of NFS, the External Data Representation 313 (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS 314 version 4 protocol are those defined in [RFC1831] and [RFC1832]. To 315 meet end to end security requirements, the RPCSEC_GSS framework 316 [RFC2203] will be used to extend the basic RPC security. With the 317 use of RPCSEC_GSS, various mechanisms can be provided to offer 318 authentication, integrity, and privacy to the NFS version 4 protocol. 319 Kerberos V5 will be used as described in [RFC1964] to provide one 320 security framework. The LIPKEY GSS-API mechanism described in 321 [RFC2847] will be used to provide for the use of user password and 322 server public key by the NFS version 4 protocol. With the use of 323 RPCSEC_GSS, other mechanisms may also be specified and used for NFS 324 version 4 security. 326 To enable in-band security negotiation, the NFS version 4 protocol 327 has added a new operation which provides the client a method of 328 querying the server about its policies regarding which security 329 mechanisms must be used for access to the server's file system 330 resources. With this, the client can securely match the security 331 mechanism that meets the policies specified at both the client and 332 server. 334 1.1.2. Procedure and Operation Structure 336 A significant departure from the previous versions of the NFS 337 protocol is the introduction of the COMPOUND procedure. For the NFS 338 version 4 protocol, there are two RPC procedures, NULL and COMPOUND. 339 The COMPOUND procedure is defined in terms of operations and these 340 operations correspond more closely to the traditional NFS procedures. 341 With the use of the COMPOUND procedure, the client is able to build 342 simple or complex requests. These COMPOUND requests allow for a 343 reduction in the number of RPCs needed for logical file system 344 operations. For example, without previous contact with a server a 345 client will be able to read data from a file in one request by 346 combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. 347 With previous versions of the NFS protocol, this type of single 348 request was not possible. 350 The model used for COMPOUND is very simple. There is no logical OR 351 or ANDing of operations. The operations combined within a COMPOUND 352 request are evaluated in order by the server. Once an operation 353 returns a failing result, the evaluation ends and the results of all 354 evaluated operations are returned to the client. 356 The NFS version 4 protocol continues to have the client refer to a 357 file or directory at the server by a "filehandle". The COMPOUND 358 procedure has a method of passing a filehandle from one operation to 359 another within the sequence of operations. There is a concept of a 360 "current filehandle" and "saved filehandle". Most operations use the 362 Draft Specification NFS version 4 Protocol November 2001 364 "current filehandle" as the file system object to operate upon. The 365 "saved filehandle" is used as temporary filehandle storage within a 366 COMPOUND procedure as well as an additional operand for certain 367 operations. 369 1.1.3. File System Model 371 The general file system model used for the NFS version 4 protocol is 372 the same as previous versions. The server file system is 373 hierarchical with the regular files contained within being treated as 374 opaque byte streams. In a slight departure, file and directory names 375 are encoded with UTF-8 to deal with the basics of 376 internationalization. 378 The NFS version 4 protocol does not require a separate protocol to 379 provide for the initial mapping between path name and filehandle. 380 Instead of using the older MOUNT protocol for this mapping, the 381 server provides a ROOT filehandle that represents the logical root or 382 top of the file system tree provided by the server. The server 383 provides multiple file systems by glueing them together with pseudo 384 file systems. These pseudo file systems provide for potential gaps 385 in the path names between real file systems. 387 1.1.3.1. Filehandle Types 389 In previous versions of the NFS protocol, the filehandle provided by 390 the server was guaranteed to be valid or persistent for the lifetime 391 of the file system object to which it referred. For some server 392 implementations, this persistence requirement has been difficult to 393 meet. For the NFS version 4 protocol, this requirement has been 394 relaxed by introducing another type of filehandle, volatile. With 395 persistent and volatile filehandle types, the server implementation 396 can match the abilities of the file system at the server along with 397 the operating environment. The client will have knowledge of the 398 type of filehandle being provided by the server and can be prepared 399 to deal with the semantics of each. 401 1.1.3.2. Attribute Types 403 The NFS version 4 protocol introduces three classes of file system or 404 file attributes. Like the additional filehandle type, the 405 classification of file attributes has been done to ease server 406 implementations along with extending the overall functionality of the 407 NFS protocol. This attribute model is structured to be extensible 408 such that new attributes can be introduced in minor revisions of the 409 protocol without requiring significant rework. 411 The three classifications are: mandatory, recommended and named 412 attributes. This is a significant departure from the previous 414 Draft Specification NFS version 4 Protocol November 2001 416 attribute model used in the NFS protocol. Previously, the attributes 417 for the file system and file objects were a fixed set of mainly Unix 418 attributes. If the server or client did not support a particular 419 attribute, it would have to simulate the attribute the best it could. 421 Mandatory attributes are the minimal set of file or file system 422 attributes that must be provided by the server and must be properly 423 represented by the server. Recommended attributes represent 424 different file system types and operating environments. The 425 recommended attributes will allow for better interoperability and the 426 inclusion of more operating environments. The mandatory and 427 recommended attribute sets are traditional file or file system 428 attributes. The third type of attribute is the named attribute. A 429 named attribute is an opaque byte stream that is associated with a 430 directory or file and referred to by a string name. Named attributes 431 are meant to be used by client applications as a method to associate 432 application specific data with a regular file or directory. 434 One significant addition to the recommended set of file attributes is 435 the Access Control List (ACL) attribute. This attribute provides for 436 directory and file access control beyond the model used in previous 437 versions of the NFS protocol. The ACL definition allows for 438 specification of user and group level access control. 440 1.1.3.3. File System Replication and Migration 442 With the use of a special file attribute, the ability to migrate or 443 replicate server file systems is enabled within the protocol. The 444 file system locations attribute provides a method for the client to 445 probe the server about the location of a file system. In the event 446 of a migration of a file system, the client will receive an error 447 when operating on the file system and it can then query as to the new 448 file system location. Similar steps are used for replication, the 449 client is able to query the server for the multiple available 450 locations of a particular file system. From this information, the 451 client can use its own policies to access the appropriate file system 452 location. 454 1.1.4. OPEN and CLOSE 456 The NFS version 4 protocol introduces OPEN and CLOSE operations. The 457 OPEN operation provides a single point where file lookup, creation, 458 and share semantics can be combined. The CLOSE operation also 459 provides for the release of state accumulated by OPEN. 461 1.1.5. File locking 463 With the NFS version 4 protocol, the support for byte range file 464 locking is part of the NFS protocol. The file locking support is 466 Draft Specification NFS version 4 Protocol November 2001 468 structured so that an RPC callback mechanism is not required. This 469 is a departure from the previous versions of the NFS file locking 470 protocol, Network Lock Manager (NLM). The state associated with file 471 locks is maintained at the server under a lease-based model. The 472 server defines a single lease period for all state held by a NFS 473 client. If the client does not renew its lease within the defined 474 period, all state associated with the client's lease may be released 475 by the server. The client may renew its lease with use of the RENEW 476 operation or implicitly by use of other operations (primarily READ). 478 1.1.6. Client Caching and Delegation 480 The file, attribute, and directory caching for the NFS version 4 481 protocol is similar to previous versions. Attributes and directory 482 information are cached for a duration determined by the client. At 483 the end of a predefined timeout, the client will query the server to 484 see if the related file system object has been updated. 486 For file data, the client checks its cache validity when the file is 487 opened. A query is sent to the server to determine if the file has 488 been changed. Based on this information, the client determines if 489 the data cache for the file should kept or released. Also, when the 490 file is closed, any modified data is written to the server. 492 If an application wants to serialize access to file data, file 493 locking of the file data ranges in question should be used. 495 The major addition to NFS version 4 in the area of caching is the 496 ability of the server to delegate certain responsibilities to the 497 client. When the server grants a delegation for a file to a client, 498 the client is guaranteed certain semantics with respect to the 499 sharing of that file with other clients. At OPEN, the server may 500 provide the client either a read or write delegation for the file. 501 If the client is granted a read delegation, it is assured that no 502 other client has the ability to write to the file for the duration of 503 the delegation. If the client is granted a write delegation, the 504 client is assured that no other client has read or write access to 505 the file. 507 Delegations can be recalled by the server. If another client 508 requests access to the file in such a way that the access conflicts 509 with the granted delegation, the server is able to notify the initial 510 client and recall the delegation. This requires that a callback path 511 exist between the server and client. If this callback path does not 512 exist, then delegations can not be granted. The essence of a 513 delegation is that it allows the client to locally service operations 514 such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate 515 interaction with the server. 517 Draft Specification NFS version 4 Protocol November 2001 519 1.2. General Definitions 521 The following definitions are provided for the purpose of providing 522 an appropriate context for the reader. 524 Client The "client" is the entity that accesses the NFS server's 525 resources. The client may be an application which contains 526 the logic to access the NFS server directly. The client 527 may also be the traditional operating system client remote 528 file system services for a set of applications. 530 In the case of file locking the client is the entity that 531 maintains a set of locks on behalf of one or more 532 applications. This client is responsible for crash or 533 failure recovery for those locks it manages. 535 Note that multiple clients may share the same transport and 536 multiple clients may exist on the same network node. 538 Clientid A 64-bit quantity used as a unique, short-hand reference to 539 a client supplied Verifier and ID. The server is 540 responsible for supplying the Clientid. 542 Lease An interval of time defined by the server for which the 543 client is irrevocably granted a lock. At the end of a 544 lease period the lock may be revoked if the lease has not 545 been extended. The lock must be revoked if a conflicting 546 lock has been granted after the lease interval. 548 All leases granted by a server have the same fixed 549 interval. Note that the fixed interval was chosen to 550 alleviate the expense a server would have in maintaining 551 state about variable length leases across server failures. 553 Lock The term "lock" is used to refer to both record (byte- 554 range) locks as well as file (share) locks unless 555 specifically stated otherwise. 557 Server The "Server" is the entity responsible for coordinating 558 client access to a set of file systems. 560 Stable Storage 561 NFS version 4 servers must be able to recover without data 562 loss from multiple power failures (including cascading 563 power failures, that is, several power failures in quick 564 succession), operating system failures, and hardware 565 failure of components other than the storage medium itself 566 (for example, disk, nonvolatile RAM). 568 Some examples of stable storage that are allowable for an 569 NFS server include: 571 Draft Specification NFS version 4 Protocol November 2001 573 1. Media commit of data, that is, the modified data has 574 been successfully written to the disk media, 575 for example, the disk platter. 577 2. An immediate reply disk drive with battery-backed 578 on-drive intermediate storage or uninterruptible power 579 system (UPS). 581 3. Server commit of data with battery-backed intermediate 582 storage and recovery software. 584 4. Cache commit with uninterruptible power system (UPS) 585 and recovery software. 587 Stateid A 64-bit quantity returned by a server that uniquely 588 defines the locking state granted by the server for a 589 specific lock owner for a specific file. 591 Stateids composed of all bits 0 or all bits 1 have special 592 meaning and are reserved values. 594 Verifier A 64-bit quantity generated by the client that the server 595 can use to determine if the client has restarted and lost 596 all previous lock state. 598 Draft Specification NFS version 4 Protocol November 2001 600 2. Protocol Data Types 602 The syntax and semantics to describe the data types of the NFS 603 version 4 protocol are defined in the XDR [RFC1832] and RPC [RFC1831] 604 documents. The next sections build upon the XDR data types to define 605 types and structures specific to this protocol. 607 2.1. Basic Data Types 609 Data Type Definition 610 _____________________________________________________________________ 611 int32_t typedef int int32_t; 613 uint32_t typedef unsigned int uint32_t; 615 int64_t typedef hyper int64_t; 617 uint64_t typedef unsigned hyper uint64_t; 619 attrlist4 typedef opaque attrlist4<>; 620 Used for file/directory attributes 622 bitmap4 typedef uint32_t bitmap4<>; 623 Used in attribute array encoding. 625 changeid4 typedef uint64_t changeid4; 626 Used in definition of change_info 628 clientid4 typedef uint64_t clientid4; 629 Shorthand reference to client identification 631 component4 typedef utf8string component4; 632 Represents path name components 634 count4 typedef uint32_t count4; 635 Various count parameters (READ, WRITE, COMMIT) 637 length4 typedef uint64_t length4; 638 Describes LOCK lengths 640 linktext4 typedef utf8string linktext4; 641 Symbolic link contents 643 mode4 typedef uint32_t mode4; 644 Mode attribute data type 646 nfs_cookie4 typedef uint64_t nfs_cookie4; 647 Opaque cookie value for READDIR 649 nfs_fh4 typedef opaque nfs_fh4; 650 Filehandle definition; NFS4_FHSIZE is defined as 128 652 Draft Specification NFS version 4 Protocol November 2001 654 nfs_ftype4 enum nfs_ftype4; 655 Various defined file types 657 nfsstat4 enum nfsstat4; 658 Return value for operations 660 offset4 typedef uint64_t offset4; 661 Various offset designations (READ, WRITE, LOCK, COMMIT) 663 pathname4 typedef component4 pathname4<>; 664 Represents path name for LOOKUP, OPEN and others 666 qop4 typedef uint32_t qop4; 667 Quality of protection designation in SECINFO 669 sec_oid4 typedef opaque sec_oid4<>; 670 Security Object Identifier 671 The sec_oid4 data type is not really opaque. 672 Instead contains an ASN.1 OBJECT IDENTIFIER as used 673 by GSS-API in the mech_type argument to 674 GSS_Init_sec_context. See [RFC2078] for details. 676 seqid4 typedef uint32_t seqid4; 677 Sequence identifier used for file locking 679 utf8string typedef opaque utf8string<>; 680 UTF-8 encoding for strings 682 verifier4 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 683 Verifier used for various operations (COMMIT, CREATE, 684 OPEN, READDIR, SETCLIENTID, WRITE) 685 NFS4_VERIFIER_SIZE is defined as 8 687 2.2. Structured Data Types 689 nfstime4 690 struct nfstime4 { 691 int64_t seconds; 692 uint32_t nseconds; 693 } 695 The nfstime4 structure gives the number of seconds and 696 nanoseconds since midnight or 0 hour January 1, 1970 Coordinated 697 Universal Time (UTC). Values greater than zero for the seconds 698 field denote dates after the 0 hour January 1, 1970. Values 699 less than zero for the seconds field denote dates before the 0 700 hour January 1, 1970. In both cases, the nseconds field is to 701 be added to the seconds field for the final time representation. 702 For example, if the time to be represented is one-half second 703 before 0 hour January 1, 1970, the seconds field would have a 705 Draft Specification NFS version 4 Protocol November 2001 707 value of negative one (-1) and the nseconds fields would have a 708 value of one-half second (500000000). Values greater than 709 999,999,999 for nseconds are considered invalid. 711 This data type is used to pass time and date information. A 712 server converts to and from its local representation of time 713 when processing time values, preserving as much accuracy as 714 possible. If the precision of timestamps stored for a file 715 system object is less than defined, loss of precision can occur. 716 An adjunct time maintenance protocol is recommended to reduce 717 client and server time skew. 719 time_how4 721 enum time_how4 { 722 SET_TO_SERVER_TIME4 = 0, 723 SET_TO_CLIENT_TIME4 = 1 724 }; 726 settime4 728 union settime4 switch (time_how4 set_it) { 729 case SET_TO_CLIENT_TIME4: 730 nfstime4 time; 731 default: 732 void; 733 }; 735 The above definitions are used as the attribute definitions to 736 set time values. If set_it is SET_TO_SERVER_TIME4, then the 737 server uses its local representation of time for the time value. 739 specdata4 741 struct specdata4 { 742 uint32_t specdata1; 743 uint32_t specdata2; 744 }; 746 This data type represents additional information for the device 747 file types NF4CHR and NF4BLK. 749 fsid4 751 struct fsid4 { 752 uint64_t major; 753 uint64_t minor; 754 }; 756 Draft Specification NFS version 4 Protocol November 2001 758 This type is the file system identifier that is used as a 759 mandatory attribute. 761 fs_location4 763 struct fs_location4 { 764 utf8string server<>; 765 pathname4 rootpath; 766 }; 768 fs_locations4 770 struct fs_locations4 { 771 pathname4 fs_root; 772 fs_location4 locations<>; 773 }; 775 The fs_location4 and fs_locations4 data types are used for the 776 fs_locations recommended attribute which is used for migration 777 and replication support. 779 fattr4 781 struct fattr4 { 782 bitmap4 attrmask; 783 attrlist4 attr_vals; 784 }; 786 The fattr4 structure is used to represent file and directory 787 attributes. 789 The bitmap is a counted array of 32 bit integers used to contain 790 bit values. The position of the integer in the array that 791 contains bit n can be computed from the expression (n / 32) and 792 its bit within that integer is (n mod 32). 794 0 1 795 +-----------+-----------+-----------+-- 796 | count | 31 .. 0 | 63 .. 32 | 797 +-----------+-----------+-----------+-- 799 change_info4 801 struct change_info4 { 802 bool atomic; 803 changeid4 before; 804 changeid4 after; 805 }; 807 Draft Specification NFS version 4 Protocol November 2001 809 This structure is used with the CREATE, LINK, REMOVE, RENAME 810 operations to let the client the know value of the change 811 attribute for the directory in which the target file system 812 object resides. 814 clientaddr4 816 struct clientaddr4 { 817 /* see struct rpcb in RFC 1833 */ 818 string r_netid<>; /* network id */ 819 string r_addr<>; /* universal address */ 820 }; 822 The clientaddr4 structure is used as part of the SETCLIENT 823 operation to either specify the address of the client that is 824 using a clientid or as part of the call back registration. 826 cb_client4 828 struct cb_client4 { 829 unsigned int cb_program; 830 clientaddr4 cb_location; 831 }; 833 This structure is used by the client to inform the server of its 834 call back address; includes the program number and client 835 address. 837 nfs_client_id4 839 struct nfs_client_id4 { 840 verifier4 verifier; 841 opaque id<>; 842 }; 844 This structure is part of the arguments to the SETCLIENTID 845 operation. 847 nfs_lockowner4 849 struct nfs_lockowner4 { 850 clientid4 clientid; 851 opaque owner<>; 852 }; 854 This structure is used to identify the owner of a OPEN share or 855 file lock. 857 Draft Specification NFS version 4 Protocol November 2001 859 stateid4 861 struct stateid4 { 862 uint32_t seqid; 863 opaque other[12]; 864 }; 866 This strucutre is used for the various state sharing mechanisms 867 between the client and server. For the client, this data 868 structure is read-only. The seqid value is the only field that 869 the client should interpret. See the section for the OPEN 870 operation for further description of how the seqid field is to 871 be interpreted. 873 Draft Specification NFS version 4 Protocol November 2001 875 3. RPC and Security Flavor 877 The NFS version 4 protocol is a Remote Procedure Call (RPC) 878 application that uses RPC version 2 and the corresponding eXternal 879 Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The 880 RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as 881 the mechanism to deliver stronger security for the NFS version 4 882 protocol. 884 3.1. Ports and Transports 886 Historically, NFS version 2 and version 3 servers have resided on 887 port 2049. The registered port 2049 [RFC1700] for the NFS protocol 888 should be the default configuration. Using the registered port for 889 NFS services means the NFS client will not need to use the RPC 890 binding protocols as described in [RFC1833]; this will allow NFS to 891 transit firewalls. 893 The transport used by the RPC service for the NFS version 4 protocol 894 MUST provide congestion control comparable to that defined for TCP in 895 [RFC2581]. If the operating environment implements TCP, the NFS 896 version 4 protocol SHOULD be supported over TCP. The NFS client and 897 server may use other transports if they support congestion control as 898 defined above and in those cases a mechanism may be provided to 899 override TCP usage in favor of another transport. 901 If TCP is used as the transport, the client and server SHOULD use 902 persistent connections. This will prevent the weakening of TCP's 903 congestion control via short lived connections and will improve 904 performance for the WAN environment by eliminating the need for SYN 905 handshakes. 907 Note that for various timers, the client and server should avoid 908 inadvertent synchronization of those timers. For further discussion 909 of the general issue refer to [Floyd]. 911 3.2. Security Flavors 913 Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, 914 AUTH_DH, and AUTH_KRB4 as security flavors. With [RFC2203] an 915 additional security flavor of RPCSEC_GSS has been introduced which 916 uses the functionality of GSS-API [RFC2078]. This allows for the use 917 of varying security mechanisms by the RPC layer without the 918 additional implementation overhead of adding RPC security flavors. 919 For NFS version 4, the RPCSEC_GSS security flavor MUST be used to 920 enable the mandatory security mechanism. Other flavors, such as, 921 AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well. 923 3.2.1. Security mechanisms for NFS version 4 925 The use of RPCSEC_GSS requires selection of: mechanism, quality of 927 Draft Specification NFS version 4 Protocol November 2001 929 protection, and service (authentication, integrity, privacy). The 930 remainder of this document will refer to these three parameters of 931 the RPCSEC_GSS security as the security triple. 933 3.2.1.1. Kerberos V5 as security triple 935 The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be 936 implemented and provide the following security triples. 938 column descriptions: 940 1 == number of pseudo flavor 941 2 == name of pseudo flavor 942 3 == mechanism's OID 943 4 == mechanism's algorithm(s) 944 5 == RPCSEC_GSS service 946 1 2 3 4 5 947 ----------------------------------------------------------------------- 948 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none 949 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity 950 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy 951 for integrity, 952 and 56 bit DES 953 for privacy. 955 Note that the pseudo flavor is presented here as a mapping aid to the 956 implementor. Because this NFS protocol includes a method to 957 negotiate security and it understands the GSS-API mechanism, the 958 pseudo flavor is not needed. The pseudo flavor is needed for NFS 959 version 3 since the security negotiation is done via the MOUNT 960 protocol. 962 For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please 963 see [RFC2623]. 965 3.2.1.2. LIPKEY as a security triple 967 The LIPKEY GSS-API mechanism as described in [RFC2847] MUST be 968 implemented and provide the following security triples. The 969 definition of the columns matches the previous subsection "Kerberos 970 V5 as security triple" 972 1 2 3 4 5 973 ----------------------------------------------------------------------- 974 390006 lipkey 1.3.6.1.5.5.9 negotiated rpc_gss_svc_none 975 390007 lipkey-i 1.3.6.1.5.5.9 negotiated rpc_gss_svc_integrity 976 390008 lipkey-p 1.3.6.1.5.5.9 negotiated rpc_gss_svc_privacy 978 The mechanism algorithm is listed as "negotiated". This is because 979 LIPKEY is layered on SPKM-3 and in SPKM-3 [RFC2847] the 981 Draft Specification NFS version 4 Protocol November 2001 983 confidentiality and integrity algorithms are negotiated. Since 984 SPKM-3 specifies HMAC-MD5 for integrity as MANDATORY, 128 bit 985 cast5CBC for confidentiality for privacy as MANDATORY, and further 986 specifies that HMAC-MD5 and cast5CBC MUST be listed first before 987 weaker algorithms, specifying "negotiated" in column 4 does not 988 impair interoperability. In the event an SPKM-3 peer does not 989 support the mandatory algorithms, the other peer is free to accept or 990 reject the GSS-API context creation. 992 Because SPKM-3 negotiates the algorithms, subsequent calls to 993 LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality 994 of protection value of 0 (zero). See section 5.2 of [RFC2025] for an 995 explanation. 997 LIPKEY uses SPKM-3 to create a secure channel in which to pass a user 998 name and password from the client to the user. Once the user name 999 and password have been accepted by the server, calls to the LIPKEY 1000 context are redirected to the SPKM-3 context. See [RFC2847] for more 1001 details. 1003 3.2.1.3. SPKM-3 as a security triple 1005 The SPKM-3 GSS-API mechanism as described in [RFC2847] MUST be 1006 implemented and provide the following security triples. The 1007 definition of the columns matches the previous subsection "Kerberos 1008 V5 as security triple". 1010 1 2 3 4 5 1011 ----------------------------------------------------------------------- 1012 390009 spkm3 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_none 1013 390010 spkm3i 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_integrity 1014 390011 spkm3p 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_privacy 1016 For a discussion as to why the mechanism algorithm is listed as 1017 "negotiated", see the previous section "LIPKEY as a security triple." 1019 Because SPKM-3 negotiates the algorithms, subsequent calls to SPKM- 1020 3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality of 1021 protection value of 0 (zero). See section 5.2 of [RFC2025] for an 1022 explanation. 1024 Even though LIPKEY is layered over SPKM-3, SPKM-3 is specified as a 1025 mandatory set of triples to handle the situations where the initiator 1026 (the client) is anonymous or where the initiator has its own 1027 certificate. If the initiator is anonymous, there will not be a user 1028 name and password to send to the target (the server). If the 1029 initiator has its own certificate, then using passwords is 1030 superfluous. 1032 Draft Specification NFS version 4 Protocol November 2001 1034 3.3. Security Negotiation 1036 With the NFS version 4 server potentially offering multiple security 1037 mechanisms, the client needs a method to determine or negotiate which 1038 mechanism is to be used for its communication with the server. The 1039 NFS server may have multiple points within its file system name space 1040 that are available for use by NFS clients. In turn the NFS server 1041 may be configured such that each of these entry points may have 1042 different or multiple security mechanisms in use. 1044 The security negotiation between client and server must be done with 1045 a secure channel to eliminate the possibility of a third party 1046 intercepting the negotiation sequence and forcing the client and 1047 server to choose a lower level of security than required or desired. 1049 3.3.1. Security Error 1051 Based on the assumption that each NFS version 4 client and server 1052 must support a minimum set of security (i.e. LIPKEY, SPKM-3, and 1053 Kerberos-V5 all under RPCSEC_GSS), the NFS client will start its 1054 communication with the server with one of the minimal security 1055 triples. During communication with the server, the client may 1056 receive an NFS error of NFS4ERR_WRONGSEC. This error allows the 1057 server to notify the client that the security triple currently being 1058 used is not appropriate for access to the server's file system 1059 resources. The client is then responsible for determining what 1060 security triples are available at the server and choose one which is 1061 appropriate for the client. 1063 3.3.2. SECINFO 1065 The new SECINFO operation will allow the client to determine, on a 1066 per filehandle basis, what security triple is to be used for server 1067 access. In general, the client will not have to use the SECINFO 1068 procedure except during initial communication with the server or when 1069 the client crosses policy boundaries at the server. It is possible 1070 that the server's policies change during the client's interaction 1071 therefore forcing the client to negotiate a new security triple. 1073 3.4. Callback RPC Authentication 1075 The callback RPC (described later) must mutually authenticate the NFS 1076 server to the principal that acquired the clientid (also described 1077 later), using the same security flavor the original SETCLIENTID 1078 operation used. Because LIPKEY is layered over SPKM-3, it is 1079 permissible for the server to use SPKM-3 and not LIPKEY for the 1080 callback even if the client used LIPKEY for SETCLIENTID. 1082 For AUTH_NONE, there are no principals, so this is a non-issue. 1084 Draft Specification NFS version 4 Protocol November 2001 1086 For AUTH_SYS, the server simply uses the AUTH_SYS credential that the 1087 user used when it set up the delegation. 1089 For AUTH_DH, one commonly used convention is that the server uses the 1090 credential corresponding to this AUTH_DH principal: 1092 unix.host@domain 1094 where host and domain are variables corresponding to the name of 1095 server host and directory services domain in which it lives such as a 1096 Network Information System domain or a DNS domain. 1098 Regardless of what security mechanism under RPCSEC_GSS is being used, 1099 the NFS server, MUST identify itself in GSS-API via a 1100 GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE 1101 names are of the form: 1103 service@hostname 1105 For NFS, the "service" element is 1107 nfs 1109 Implementations of security mechanisms will convert nfs@hostname to 1110 various different forms. For Kerberos V5 and LIPKEY, the following 1111 form is RECOMMENDED: 1113 nfs/hostname 1115 For Kerberos V5, nfs/hostname would be a server principal in the 1116 Kerberos Key Distribution Center database. For LIPKEY, this would be 1117 the username passed to the target (the NFS version 4 client that 1118 receives the callback). 1120 It should be noted that LIPKEY may not work for callbacks, since the 1121 LIPKEY client uses a user id/password. If the NFS client receiving 1122 the callback can authenticate the NFS server's user name/password 1123 pair, and if the user that the NFS server is authenticating to has a 1124 public key certificate, then it works. 1126 In situations where NFS client uses LIPKEY and uses a per-host 1127 principal for the SETCLIENTID operation, instead of using LIPKEY for 1128 SETCLIENTID, it is RECOMMENDED that SPKM-3 with mutual authentication 1129 be used. This effectively means that the client will use a 1130 certificate to authenticate and identify the initiator to the target 1131 on the NFS server. Using SPKM-3 and not LIPKEY has the following 1132 advantages: 1134 o When the server does a callback, it must authenticate to the 1135 principal used in the SETCLIENTID. Even if LIPKEY is used, 1136 because LIPKEY is layered over SPKM-3, the NFS client will need 1137 to have a certificate that corresponds to the principal used in 1139 Draft Specification NFS version 4 Protocol November 2001 1141 the SETCLIENTID operation. From an administrative perspective, 1142 having a user name, password, and certificate for both the 1143 client and server is redundant. 1145 o LIPKEY was intended to minimize additional infrastructure 1146 requirements beyond a certificate for the target, and the 1147 expectation is that existing password infrastructure can be 1148 leveraged for the initiator. In some environments, a per-host 1149 password does not exist yet. If certificates are used for any 1150 per-host principals, then additional password infrastructure is 1151 not needed. 1153 o In cases when a host is both an NFS client and server, it can 1154 share the same per-host certificate. 1156 Draft Specification NFS version 4 Protocol November 2001 1158 4. Filehandles 1160 The filehandle in the NFS protocol is a per server unique identifier 1161 for a file system object. The contents of the filehandle are opaque 1162 to the client. Therefore, the server is responsible for translating 1163 the filehandle to an internal representation of the file system 1164 object. Since the filehandle is the client's reference to an object 1165 and the client may cache this reference, the server SHOULD not reuse 1166 a filehandle for another file system object. If the server needs to 1167 reuse a filehandle value, the time elapsed before reuse SHOULD be 1168 large enough such that it is unlikely the client has a cached copy of 1169 the reused filehandle value. Note that a client may cache a 1170 filehandle for a very long time. For example, a client may cache NFS 1171 data to local storage as a method to expand its effective cache size 1172 and as a means to survive client restarts. Therefore, the lifetime 1173 of a cached filehandle may be extended. 1175 4.1. Obtaining the First Filehandle 1177 The operations of the NFS protocol are defined in terms of one or 1178 more filehandles. Therefore, the client needs a filehandle to 1179 initiate communication with the server. With the NFS version 2 1180 protocol [RFC1094] and the NFS version 3 protocol [RFC1813], there 1181 exists an ancillary protocol to obtain this first filehandle. The 1182 MOUNT protocol, RPC program number 100005, provides the mechanism of 1183 translating a string based file system path name to a filehandle 1184 which can then be used by the NFS protocols. 1186 The MOUNT protocol has deficiencies in the area of security and use 1187 via firewalls. This is one reason that the use of the public 1188 filehandle was introduced in [RFC2054] and [RFC2055]. With the use 1189 of the public filehandle in combination with the LOOKUP procedure in 1190 the NFS version 2 and 3 protocols, it has been demonstrated that the 1191 MOUNT protocol is unnecessary for viable interaction between NFS 1192 client and server. 1194 Therefore, the NFS version 4 protocol will not use an ancillary 1195 protocol for translation from string based path names to a 1196 filehandle. Two special filehandles will be used as starting points 1197 for the NFS client. 1199 4.1.1. Root Filehandle 1201 The first of the special filehandles is the ROOT filehandle. The 1202 ROOT filehandle is the "conceptual" root of the file system name 1203 space at the NFS server. The client uses or starts with the ROOT 1204 filehandle by employing the PUTROOTFH operation. The PUTROOTFH 1205 operation instructs the server to set the "current" filehandle to the 1206 ROOT of the server's file tree. Once this PUTROOTFH operation is 1207 used, the client can then traverse the entirety of the server's file 1209 Draft Specification NFS version 4 Protocol November 2001 1211 tree with the LOOKUP procedure. A complete discussion of the server 1212 name space is in the section "NFS Server Name Space". 1214 4.1.2. Public Filehandle 1216 The second special filehandle is the PUBLIC filehandle. Unlike the 1217 ROOT filehandle, the PUBLIC filehandle may be bound or represent an 1218 arbitrary file system object at the server. The server is 1219 responsible for this binding. It may be that the PUBLIC filehandle 1220 and the ROOT filehandle refer to the same file system object. 1221 However, it is up to the administrative software at the server and 1222 the policies of the server administrator to define the binding of the 1223 PUBLIC filehandle and server file system object. The client may not 1224 make any assumptions about this binding. 1226 4.2. Filehandle Types 1228 In the NFS version 2 and 3 protocols, there was one type of 1229 filehandle with a single set of semantics. The NFS version 4 1230 protocol introduces a new type of filehandle in an attempt to 1231 accommodate certain server environments. The first type of 1232 filehandle is 'persistent'. The semantics of a persistent filehandle 1233 are the same as the filehandles of the NFS version 2 and 3 protocols. 1234 The second or new type of filehandle is the "volatile" filehandle. 1236 The volatile filehandle type is being introduced to address server 1237 functionality or implementation issues which make correct 1238 implementation of a persistent filehandle infeasible. Some server 1239 environments do not provide a file system level invariant that can be 1240 used to construct a persistent filehandle. The underlying server 1241 file system may not provide the invariant or the server's file system 1242 programming interfaces may not provide access to the needed 1243 invariant. Volatile filehandles may ease the implementation of 1244 server functionality such as hierarchical storage management or file 1245 system reorganization or migration. However, the volatile filehandle 1246 increases the implementation burden for the client. However this 1247 increased burden is deemed acceptable based on the overall gains 1248 achieved by the protocol. 1250 Since the client will need to handle persistent and volatile 1251 filehandle differently, a file attribute is defined which may be used 1252 by the client to determine the filehandle types being returned by the 1253 server. 1255 4.2.1. General Properties of a Filehandle 1257 The filehandle contains all the information the server needs to 1258 distinguish an individual file. To the client, the filehandle is 1259 opaque. The client stores filehandles for use in a later request and 1261 Draft Specification NFS version 4 Protocol November 2001 1263 can compare two filehandles from the same server for equality by 1264 doing a byte-by-byte comparison. However, the client MUST NOT 1265 otherwise interpret the contents of filehandles. If two filehandles 1266 from the same server are equal, they MUST refer to the same file. If 1267 they are not equal, the client may use information provided by the 1268 server, in the form of file attributes, to determine whether they 1269 denote the same files or different files. The client would do this 1270 as necessary for client side caching. Servers SHOULD try to maintain 1271 a one-to-one correspondence between filehandles and files but this is 1272 not required. Clients MUST use filehandle comparisons only to 1273 improve performance, not for correct behavior. All clients need to 1274 be prepared for situations in which it cannot be determined whether 1275 two filehandles denote the same object and in such cases, avoid 1276 making invalid assumpions which might cause incorrect behavior. 1277 Further discussion of filehandle and attribute comparison in the 1278 context of data caching is presented in the section "Data Caching and 1279 File Identity". 1281 As an example, in the case that two different path names when 1282 traversed at the server terminate at the same file system object, the 1283 server SHOULD return the same filehandle for each path. This can 1284 occur if a hard link is used to create two file names which refer to 1285 the same underlying file object and associated data. For example, if 1286 paths /a/b/c and /a/d/c refer to the same file, the server SHOULD 1287 return the same filehandle for both path names traversals. 1289 4.2.2. Persistent Filehandle 1291 A persistent filehandle is defined as having a fixed value for the 1292 lifetime of the file system object to which it refers. Once the 1293 server creates the filehandle for a file system object, the server 1294 MUST accept the same filehandle for the object for the lifetime of 1295 the object. If the server restarts or reboots the NFS server must 1296 honor the same filehandle value as it did in the server's previous 1297 instantiation. Similarly, if the file system is migrated, the new 1298 NFS server must honor the same file handle as the old NFS server. 1300 The persistent filehandle will be become stale or invalid when the 1301 file system object is removed. When the server is presented with a 1302 persistent filehandle that refers to a deleted object, it MUST return 1303 an error of NFS4ERR_STALE. A filehandle may become stale when the 1304 file system containing the object is no longer available. The file 1305 system may become unavailable if it exists on removable media and the 1306 media is no longer available at the server or the file system in 1307 whole has been destroyed or the file system has simply been removed 1308 from the server's name space (i.e. unmounted in a Unix environment). 1310 4.2.3. Volatile Filehandle 1312 A volatile filehandle does not share the same longevity 1314 Draft Specification NFS version 4 Protocol November 2001 1316 characteristics of a persistent filehandle. The server may determine 1317 that a volatile filehandle is no longer valid at many different 1318 points in time. If the server can definitively determine that a 1319 volatile filehandle refers to an object that has been removed, the 1320 server should return NFS4ERR_STALE to the client (as is the case for 1321 persistent filehandles). In all other cases where the server 1322 determines that a volatile filehandle can no longer be used, it 1323 should return an error of NFS4ERR_FHEXPIRED. 1325 The mandatory attribute "fh_expire_type" is used by the client to 1326 determine what type of filehandle the server is providing for a 1327 particular file system. This attribute is a bitmask with the 1328 following values: 1330 FH4_PERSISTENT 1331 The value of FH4_PERSISTENT is used to indicate a persistent 1332 filehandle, which is valid until the object is removed from the 1333 file system. The server will not return NFS4ERR_FHEXPIRED for 1334 this filehandle. FH4_PERSISTENT is defined as a value in which 1335 none of the bits specified below are set. 1337 FH4_NOEXPIRE_WITH_OPEN 1338 The filehandle will not expire while client has the file open. 1339 If this bit is set, then the values FH4_VOLATILE_ANY or 1340 FH4_VOL_RENAME do not impact expiration while the file is open. 1341 Once the file is closed or if the FH4_NOEXPIRE_WITH_OPEN bit is 1342 false, the rest of the volatile related bits apply. 1344 FH4_VOLATILE_ANY 1345 The filehandle may expire at any time and will expire during 1346 system migration and rename. 1348 FH4_VOL_MIGRATION 1349 The filehandle will expire during file system migration. May 1350 only be set if FH4_VOLATILE_ANY is not set. 1352 FH4_VOL_RENAME 1353 The filehandle may expire due to a rename. This includes a 1354 rename by the requesting client or a rename by another client. 1355 May only be set if FH4_VOLATILE_ANY is not set. 1357 Servers which provide volatile filehandles should deny a RENAME or 1358 REMOVE that would affect an OPEN file or any of the components 1359 leading to the OPEN file. In addition, the server should deny all 1360 RENAME or REMOVE requests during the grace or lease period upon 1361 server restart. 1363 The reader may be wondering why there are three FH4_VOL* bits and why 1364 FH4_VOLATILE_ANY is exclusive of FH4_VOL_MIGRATION and 1365 FH4_VOL_RENAME. If the a filehandle is normally persistent but 1366 cannot persist across a file set migration, then the presence of the 1368 Draft Specification NFS version 4 Protocol November 2001 1370 FH4_VOL_MIGRATION or FH4_VOL_RENAME tells the client that it can 1371 treat the file handle as persistent for purposes of maintaining a 1372 file name to file handle cache, except for the specific event 1373 described by the bit. However, FH4_VOLATILE_ANY tells the client 1374 that it should not maintain such a cache for unopened files. A 1375 server MUST not present FH4_VOLATILE_ANY with FH4_VOL_MIGRATION or 1376 FH4_VOL_RENAME as this will lead to confusion. FH4_VOLATILE_ANY 1377 implies that the file handle will expire upon migration or rename, in 1378 addition to other events. 1380 4.2.4. One Method of Constructing a Volatile Filehandle 1382 As mentioned, in some instances a filehandle is stale (no longer 1383 valid; perhaps because the file was removed from the server) or it is 1384 expired (the underlying file is valid but since the filehandle is 1385 volatile, it may have expired). Thus the server needs to be able to 1386 return NFS4ERR_STALE in the former case and NFS4ERR_FHEXPIRED in the 1387 latter case. This can be done by careful construction of the volatile 1388 filehandle. One possible implementation follows. 1390 A volatile filehandle, while opaque to the client could contain: 1392 [volatile bit = 1 | server boot time | slot | generation number] 1394 o slot is an index in the server volatile filehandle table 1396 o generation number is the generation number for the table 1397 entry/slot 1399 If the server boot time is less than the current server boot time, 1400 return NFS4ERR_FHEXPIRED. If slot is out of range, return 1401 NFS4ERR_BADHANDLE. If the generation number does not match, return 1402 NFS4ERR_FHEXPIRED. 1404 When the server reboots, the table is gone (it is volatile). 1406 If volatile bit is 0, then it is a persistent filehandle with a 1407 different structure following it. 1409 4.3. Client Recovery from Filehandle Expiration 1411 If possible, the client SHOULD recover from the receipt of an 1412 NFS4ERR_FHEXPIRED error. The client must take on additional 1413 responsibility so that it may prepare itself to recover from the 1414 expiration of a volatile filehandle. If the server returns 1415 persistent filehandles, the client does not need these additional 1416 steps. 1418 Draft Specification NFS version 4 Protocol November 2001 1420 For volatile filehandles, most commonly the client will need to store 1421 the component names leading up to and including the file system 1422 object in question. With these names, the client should be able to 1423 recover by finding a filehandle in the name space that is still 1424 available or by starting at the root of the server's file system name 1425 space. 1427 If the expired filehandle refers to an object that has been removed 1428 from the file system, obviously the client will not be able to 1429 recover from the expired filehandle. 1431 It is also possible that the expired filehandle refers to a file that 1432 has been renamed. If the file was renamed by another client, again 1433 it is possible that the original client will not be able to recover. 1434 However, in the case that the client itself is renaming the file and 1435 the file is open, it is possible that the client may be able to 1436 recover. The client can determine the new path name based on the 1437 processing of the rename request. The client can then regenerate the 1438 new filehandle based on the new path name. The client could also use 1439 the compound operation mechanism to construct a set of operations 1440 like: 1441 RENAME A B 1442 LOOKUP B 1443 GETFH 1445 Draft Specification NFS version 4 Protocol November 2001 1447 5. File Attributes 1449 To meet the requirements of extensibility and increased 1450 interoperability with non-Unix platforms, attributes must be handled 1451 in a flexible manner. The NFS Version 3 fattr3 structure contains a 1452 fixed list of attributes that not all clients and servers are able to 1453 support or care about. The fattr3 structure can not be extended as 1454 new needs arise and it provides no way to indicate non-support. With 1455 the NFS Version 4 protocol, the client will be able to ask what 1456 attributes the server supports and will be able to request only those 1457 attributes in which it is interested. 1459 To this end, attributes will be divided into three groups: mandatory, 1460 recommended, and named. Both mandatory and recommended attributes 1461 are supported in the NFS version 4 protocol by a specific and well- 1462 defined encoding and are identified by number. They are requested by 1463 setting a bit in the bit vector sent in the GETATTR request; the 1464 server response includes a bit vector to list what attributes were 1465 returned in the response. New mandatory or recommended attributes 1466 may be added to the NFS protocol between major revisions by 1467 publishing a standards-track RFC which allocates a new attribute 1468 number value and defines the encoding for the attribute. See the 1469 section "Minor Versioning" for further discussion. 1471 Named attributes are accessed by the new OPENATTR operation, which 1472 accesses a hidden directory of attributes associated with a file 1473 system object. OPENATTR takes a filehandle for the object and 1474 returns the filehandle for the attribute hierarchy. The filehandle 1475 for the named attributes is a directory object accessible by LOOKUP 1476 or READDIR and contains files whose names represent the named 1477 attributes and whose data bytes are the value of the attribute. For 1478 example: 1480 LOOKUP "foo" ; look up file 1481 GETATTR attrbits 1482 OPENATTR ; access foo's named attributes 1483 LOOKUP "x11icon" ; look up specific attribute 1484 READ 0,4096 ; read stream of bytes 1486 Named attributes are intended for data needed by applications rather 1487 than by an NFS client implementation. NFS implementors are strongly 1488 encouraged to define their new attributes as recommended attributes 1489 by bringing them to the IETF standards-track process. 1491 The set of attributes which are classified as mandatory is 1492 deliberately small since servers must do whatever it takes to support 1493 them. The recommended attributes may be unsupported; though a server 1494 should support as many as it can. Attributes are deemed mandatory if 1495 the data is both needed by a large number of clients and is not 1496 otherwise reasonably computable by the client when support is not 1498 Draft Specification NFS version 4 Protocol November 2001 1500 provided on the server. 1502 5.1. Mandatory Attributes 1504 These MUST be supported by every NFS Version 4 client and server in 1505 order to ensure a minimum level of interoperability. The server must 1506 store and return these attributes and the client must be able to 1507 function with an attribute set limited to these attributes. With 1508 just the mandatory attributes some client functionality may be 1509 impaired or limited in some ways. A client may ask for any of these 1510 attributes to be returned by setting a bit in the GETATTR request and 1511 the server must return their value. 1513 5.2. Recommended Attributes 1515 These attributes are understood well enough to warrant support in the 1516 NFS Version 4 protocol. However, they may not be supported on all 1517 clients and servers. A client may ask for any of these attributes to 1518 be returned by setting a bit in the GETATTR request but must handle 1519 the case where the server does not return them. A client may ask for 1520 the set of attributes the server supports and should not request 1521 attributes the server does not support. A server should be tolerant 1522 of requests for unsupported attributes and simply not return them 1523 rather than considering the request an error. It is expected that 1524 servers will support all attributes they comfortably can and only 1525 fail to support attributes which are difficult to support in their 1526 operating environments. A server should provide attributes whenever 1527 they don't have to "tell lies" to the client. For example, a file 1528 modification time should be either an accurate time or should not be 1529 supported by the server. This will not always be comfortable to 1530 clients but it seems that the client has a better ability to 1531 fabricate or construct an attribute or do without the attribute. 1533 5.3. Named Attributes 1535 These attributes are not supported by direct encoding in the NFS 1536 Version 4 protocol but are accessed by string names rather than 1537 numbers and correspond to an uninterpreted stream of bytes which are 1538 stored with the file system object. The name space for these 1539 attributes may be accessed by using the OPENATTR operation. The 1540 OPENATTR operation returns a filehandle for a virtual "attribute 1541 directory" and further perusal of the name space may be done using 1542 READDIR and LOOKUP operations on this filehandle. Named attributes 1543 may then be examined or changed by normal READ and WRITE and CREATE 1544 operations on the filehandles returned from READDIR and LOOKUP. 1545 Named attributes may have attributes. 1547 It is recommended that servers support arbitrary named attributes. A 1548 client should not depend on the ability to store any named attributes 1550 Draft Specification NFS version 4 Protocol November 2001 1552 in the server's file system. If a server does support named 1553 attributes, a client which is also able to handle them should be able 1554 to copy a file's data and meta-data with complete transparency from 1555 one location to another; this would imply that names allowed for 1556 regular directory entries are valid for named attribute names as 1557 well. 1559 Names of attributes will not be controlled by this document or other 1560 IETF standards track documents. See the section "IANA 1561 Considerations" for further discussion. 1563 Draft Specification NFS version 4 Protocol November 2001 1565 5.4. Mandatory Attributes - Definitions 1567 Name # DataType Access Description 1568 ___________________________________________________________________ 1569 supp_attr 0 bitmap READ The bit vector which 1570 would retrieve all 1571 mandatory and 1572 recommended attributes 1573 that are supported for 1574 this object. 1576 type 1 nfs4_ftype READ The type of the object 1577 (file, directory, 1578 symlink) 1580 fh_expire_type 2 uint32 READ Server uses this to 1581 specify filehandle 1582 expiration behavior to 1583 the client. See the 1584 section "Filehandles" 1585 for additional 1586 description. 1588 change 3 uint64 READ A value created by the 1589 server that the client 1590 can use to determine 1591 if file data, 1592 directory contents or 1593 attributes of the 1594 object have been 1595 modified. The server 1596 may return the 1597 object's time_modify 1598 attribute for this 1599 attribute's value but 1600 only if the file 1601 system object can not 1602 be updated more 1603 frequently than the 1604 resolution of 1605 time_modify. 1607 size 4 uint64 R/W The size of the object 1608 in bytes. 1610 link_support 5 bool READ Does the object's file 1611 system supports hard 1612 links? 1614 Draft Specification NFS version 4 Protocol November 2001 1616 symlink_support 6 bool READ Does the object's file 1617 system supports 1618 symbolic links? 1620 named_attr 7 bool READ Does this object have 1621 named attributes? 1623 fsid 8 fsid4 READ Unique file system 1624 identifier for the 1625 file system holding 1626 this object. fsid 1627 contains major and 1628 minor components each 1629 of which are uint64. 1631 unique_handles 9 bool READ Are two distinct 1632 filehandles guaranteed 1633 to refer to two 1634 different file system 1635 objects? 1637 lease_time 10 nfs_lease4 READ Duration of leases at 1638 server in seconds. 1640 rdattr_error 11 enum READ Error returned from 1641 getattr during 1642 readdir. 1644 filehandle 19 nfs_fh4 READ The filehandle of this 1645 object (primarily for 1646 readdir requests). 1648 Draft Specification NFS version 4 Protocol November 2001 1650 5.5. Recommended Attributes - Definitions 1652 Name # Data Type Access Description 1653 _____________________________________________________________________ 1654 ACL 12 nfsace4<> R/W The access control 1655 list for the object. 1657 aclsupport 13 uint32 READ Indicates what types 1658 of ACLs are supported 1659 on the current file 1660 system. 1662 archive 14 bool R/W Whether or not this 1663 file has been 1664 archived since the 1665 time of last 1666 modification 1667 (deprecated in favor 1668 of time_backup). 1670 cansettime 15 bool READ Is the server able to 1671 change the times for 1672 a file system object 1673 as specified in a 1674 SETATTR operation? 1676 case_insensitive 16 bool READ Are filename 1677 comparisons on this 1678 file system case 1679 insensitive? 1681 case_preserving 17 bool READ Is filename case on 1682 this file system 1683 preserved? 1685 chown_restricted 18 bool READ If TRUE, the server 1686 will reject any 1687 request to change 1688 either the owner or 1689 the group associated 1690 with a file if the 1691 caller is not a 1692 privileged user (for 1693 example, "root" in 1694 Unix operating 1695 environments or in NT 1696 the "Take Ownership" 1697 privilege) 1699 Draft Specification NFS version 4 Protocol November 2001 1701 fileid 20 uint64 READ A number uniquely 1702 identifying the file 1703 within the file 1704 system. 1706 files_avail 21 uint64 READ File slots available 1707 to this user on the 1708 file system 1709 containing this 1710 object - this should 1711 be the smallest 1712 relevant limit. 1714 files_free 22 uint64 READ Free file slots on 1715 the file system 1716 containing this 1717 object - this should 1718 be the smallest 1719 relevant limit. 1721 files_total 23 uint64 READ Total file slots on 1722 the file system 1723 containing this 1724 object. 1726 fs_locations 24 fs_locations READ Locations where this 1727 file system may be 1728 found. If the server 1729 returns NFS4ERR_MOVED 1730 as an error, this 1731 attribute must be 1732 supported. 1734 hidden 25 bool R/W Is file considered 1735 hidden with respect 1736 to the WIN32 API? 1738 homogeneous 26 bool READ Whether or not this 1739 object's file system 1740 is homogeneous, i.e. 1741 are per file system 1742 attributes the same 1743 for all file system's 1744 objects. 1746 maxfilesize 27 uint64 READ Maximum supported 1747 file size for the 1748 file system of this 1749 object. 1751 Draft Specification NFS version 4 Protocol November 2001 1753 maxlink 28 uint32 READ Maximum number of 1754 links for this 1755 object. 1757 maxname 29 uint32 READ Maximum filename size 1758 supported for this 1759 object. 1761 maxread 30 uint64 READ Maximum read size 1762 supported for this 1763 object. 1765 maxwrite 31 uint64 READ Maximum write size 1766 supported for this 1767 object. This 1768 attribute SHOULD be 1769 supported if the file 1770 is writable. Lack of 1771 this attribute can 1772 lead to the client 1773 either wasting 1774 bandwidth or not 1775 receiving the best 1776 performance. 1778 mimetype 32 utf8<> R/W MIME body 1779 type/subtype of this 1780 object. 1782 mode 33 mode4 R/W Unix-style permission 1783 bits for this object 1784 (deprecated in favor 1785 of ACLs) 1787 no_trunc 34 bool READ If a name longer than 1788 name_max is used, 1789 will an error be 1790 returned or will the 1791 name be truncated? 1793 numlinks 35 uint32 READ Number of hard links 1794 to this object. 1796 owner 36 utf8<> R/W The string name of 1797 the owner of this 1798 object. 1800 owner_group 37 utf8<> R/W The string name of 1801 the group ownership 1802 of this object. 1804 Draft Specification NFS version 4 Protocol November 2001 1806 quota_avail_hard 38 uint64 READ For definition see 1807 "Quota Attributes" 1808 section below. 1810 quota_avail_soft 39 uint64 READ For definition see 1811 "Quota Attributes" 1812 section below. 1814 quota_used 40 uint64 READ For definition see 1815 "Quota Attributes" 1816 section below. 1818 rawdev 41 specdata4 READ Raw device 1819 identifier. Unix 1820 device major/minor 1821 node information. 1823 space_avail 42 uint64 READ Disk space in bytes 1824 available to this 1825 user on the file 1826 system containing 1827 this object - this 1828 should be the 1829 smallest relevant 1830 limit. 1832 space_free 43 uint64 READ Free disk space in 1833 bytes on the file 1834 system containing 1835 this object - this 1836 should be the 1837 smallest relevant 1838 limit. 1840 space_total 44 uint64 READ Total disk space in 1841 bytes on the file 1842 system containing 1843 this object. 1845 space_used 45 uint64 READ Number of file system 1846 bytes allocated to 1847 this object. 1849 system 46 bool R/W Is this file a system 1850 file with respect to 1851 the WIN32 API? 1853 time_access 47 nfstime4 READ The time of last 1854 access to the object. 1856 Draft Specification NFS version 4 Protocol November 2001 1858 time_access_set 48 settime4 WRITE Set the time of last 1859 access to the object. 1860 SETATTR use only. 1862 time_backup 49 nfstime4 R/W The time of last 1863 backup of the object. 1865 time_create 50 nfstime4 R/W The time of creation 1866 of the object. This 1867 attribute does not 1868 have any relation to 1869 the traditional Unix 1870 file attribute 1871 "ctime" or "change 1872 time". 1874 time_delta 51 nfstime4 READ Smallest useful 1875 server time 1876 granularity. 1878 time_metadata 52 nfstime4 R/W The time of last 1879 meta-data 1880 modification of the 1881 object. 1883 time_modify 53 nfstime4 READ The time of last 1884 modification to the 1885 object. 1887 time_modify_set 54 settime4 WRITE Set the time of last 1888 modification to the 1889 object. SETATTR use 1890 only. 1892 5.6. Interpreting owner and owner_group 1894 The recommended attributes "owner" and "owner_group" are represented 1895 in terms of a UTF-8 string. To avoid a representation that is tied 1896 to a particular underlying implementation at the client or server, 1897 the use of the UTF-8 string has been chosen. Note that section 6.1 1898 of [RFC2624] provides additional rationale. It is expected that the 1899 client and server will have their own local representation of owner 1900 and owner_group that is used for local storage or presentation to the 1901 end user. Therefore, it is expected that when these attributes are 1902 transferred between the client and server that the local 1903 representation is translated to a syntax of the form 1904 "user@dns_domain". This will allow for a client and server that do 1905 not use the same local representation the ability to translate to a 1906 common syntax that can be interpreted by both. 1908 Draft Specification NFS version 4 Protocol November 2001 1910 The translation is not specified as part of the protocol. This 1911 allows various solutions to be employed. For example, a local 1912 translation table may be consulted that maps between a numeric id to 1913 the user@dns_domain syntax. A name service may also be used to 1914 accomplish the translation. The "dns_domain" portion of the owner 1915 string is meant to be a DNS domain name. For example, user@ietf.org. 1917 In the case where there is no translation available to the client or 1918 server, the attribute value must be constructed without the "@". 1919 Therefore, the absence of the @ from the owner or owner_group 1920 attribute signifies that no translation was available and the 1921 receiver of the attribute should not place any special meaning with 1922 the attribute value. Even though the attribute value can not be 1923 translated, it may still be useful. In the case of a client, the 1924 attribute string may be used for local display of ownership. 1926 5.7. Character Case Attributes 1928 With respect to the case_insensitive and case_preserving attributes, 1929 each UCS-4 character (which UTF-8 encodes) has a "long descriptive 1930 name" [RFC1345] which may or may not included the word "CAPITAL" or 1931 "SMALL". The presence of SMALL or CAPITAL allows an NFS server to 1932 implement unambiguous and efficient table driven mappings for case 1933 insensitive comparisons, and non-case-preserving storage. For 1934 general character handling and internationalization issues, see the 1935 section "Internationalization". 1937 5.8. Quota Attributes 1939 For the attributes related to file system quotas, the following 1940 definitions apply: 1942 quota_avail_soft 1943 The value in bytes which represents the amount of additional 1944 disk space that can be allocated to this file or directory 1945 before the user may reasonably be warned. It is understood that 1946 this space may be consumed by allocations to other files or 1947 directories though there is a rule as to which other files or 1948 directories. 1950 quota_avail_hard 1951 The value in bytes which represent the amount of additional disk 1952 space beyond the current allocation that can be allocated to 1953 this file or directory before further allocations will be 1954 refused. It is understood that this space may be consumed by 1955 allocations to other files or directories. 1957 quota_used 1959 Draft Specification NFS version 4 Protocol November 2001 1961 The value in bytes which represent the amount of disc space used 1962 by this file or directory and possibly a number of other similar 1963 files or directories, where the set of "similar" meets at least 1964 the criterion that allocating space to any file or directory in 1965 the set will reduce the "quota_avail_hard" of every other file 1966 or directory in the set. 1968 Note that there may be a number of distinct but overlapping sets 1969 of files or directories for which a quota_used value is 1970 maintained. E.g. "all files with a given owner", "all files with 1971 a given group owner". etc. 1973 The server is at liberty to choose any of those sets but should 1974 do so in a repeatable way. The rule may be configured per- 1975 filesystem or may be "choose the set with the smallest quota". 1977 5.9. Access Control Lists 1979 The NFS ACL attribute is an array of access control entries (ACE). 1980 There are various access control entry types. The server is able to 1981 communicate which ACE types are supported by returning the 1982 appropriate value within the aclsupport attribute. The types of ACEs 1983 are defined as follows: 1985 Type Description 1986 _____________________________________________________ 1987 ALLOW Explicitly grants the access defined in 1988 acemask4 to the file or directory. 1990 DENY Explicitly denies the access defined in 1991 acemask4 to the file or directory. 1993 AUDIT LOG (system dependent) any access 1994 attempt to a file or directory which 1995 uses any of the access methods specified 1996 in acemask4. 1998 ALARM Generate a system ALARM (system 1999 dependent) when any access attempt is 2000 made to a file or directory for the 2001 access methods specified in acemask4. 2003 The NFS ACE attribute is defined as follows: 2005 typedef uint32_t acetype4; 2006 typedef uint32_t aceflag4; 2007 typedef uint32_t acemask4; 2009 struct nfsace4 { 2010 acetype4 type; 2011 aceflag4 flag; 2013 Draft Specification NFS version 4 Protocol November 2001 2015 acemask4 access_mask; 2016 utf8string who; 2017 }; 2019 To determine if an ACCESS or OPEN request succeeds each nfsace4 entry 2020 is processed in order by the server. Only ACEs which have a "who" 2021 that matches the requester are considered. Each ACE is processed 2022 until all of the bits of the requester's access have been ALLOWED. 2023 Once a bit (see below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it 2024 is no longer considered in the processing of later ACEs. If an 2025 ACCESS_DENIED_ACE is encountered where the requester's mode still has 2026 unALLOWED bits in common with the "access_mask" of the ACE, the 2027 request is denied. 2029 The bitmask constants used to represent the above definitions within 2030 the aclsupport attribute are as follows: 2032 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 2033 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 2034 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 2035 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 2037 5.9.1. ACE type 2039 The semantics of the "type" field follow the descriptions provided 2040 above. 2042 The bitmask constants used for the type field are as follows: 2044 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 2045 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 2046 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 2047 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 2049 5.9.2. ACE flag 2051 The "flag" field contains values based on the following descriptions. 2053 ACE4_FILE_INHERIT_ACE 2055 Can be placed on a directory and indicates that this ACE should be 2056 added to each new non-directory file created. 2058 ACE4_DIRECTORY_INHERIT_ACE 2060 Can be placed on a directory and indicates that this ACE should be 2061 added to each new directory created. 2063 Draft Specification NFS version 4 Protocol November 2001 2065 ACE4_INHERIT_ONLY_ACE 2067 Can be placed on a directory but does not apply to the directory, 2068 only to newly created files/directories as specified by the above two 2069 flags. 2071 ACE4_NO_PROPAGATE_INHERIT_ACE 2073 Can be placed on a directory. Normally when a new directory is 2074 created and an ACE exists on the parent directory which is marked 2075 ACL4_DIRECTORY_INHERIT_ACE, two ACEs are placed on the new directory. 2076 One for the directory itself and one which is an inheritable ACE for 2077 newly created directories. This flag tells the server to not place 2078 an ACE on the newly created directory which is inheritable by 2079 subdirectories of the created directory. 2081 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 2083 ACL4_FAILED_ACCESS_ACE_FLAG 2085 Both indicate for AUDIT and ALARM which state to log the event. On 2086 every ACCESS or OPEN call which occurs on a file or directory which 2087 has an ACL that is of type ACE4_SYSTEM_AUDIT_ACE_TYPE or 2088 ACE4_SYSTEM_ALARM_ACE_TYPE, the attempted access is compared to the 2089 ace4mask of these ACLs. If the access is a subset of ace4mask and the 2090 identifier match, an AUDIT trail or an ALARM is generated. By 2091 default this happens regardless of the success or failure of the 2092 ACCESS or OPEN call. 2094 The flag ACE4_SUCCESSFUL_ACCESS_ACE_FLAG only produces the AUDIT or 2095 ALARM if the ACCESS or OPEN call is successful. The 2096 ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS 2097 or OPEN call fails. 2099 ACE4_IDENTIFIER_GROUP 2101 Indicates that the "who" refers to a GROUP as defined under Unix. 2103 The bitmask constants used for the flag field are as follows: 2105 const ACE4_FILE_INHERIT_ACE = 0x00000001; 2106 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 2107 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 2108 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 2109 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 2110 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 2111 const ACE4_IDENTIFIER_GROUP = 0x00000040; 2113 Draft Specification NFS version 4 Protocol November 2001 2115 5.9.3. ACE Access Mask 2117 The access_mask field contains values based on the following: 2119 Access Description 2120 _______________________________________________________________ 2121 READ_DATA Permission to read the data of the file 2122 LIST_DIRECTORY Permission to list the contents of a 2123 directory 2124 WRITE_DATA Permission to modify the file's data 2125 ADD_FILE Permission to add a new file to a 2126 directory 2127 APPEND_DATA Permission to append data to a file 2128 ADD_SUBDIRECTORY Permission to create a subdirectory to a 2129 directory 2130 READ_NAMED_ATTRS Permission to read the named attributes 2131 of a file 2132 WRITE_NAMED_ATTRS Permission to write the named attributes 2133 of a file 2134 EXECUTE Permission to execute a file 2135 DELETE_CHILD Permission to delete a file or directory 2136 within a directory 2137 READ_ATTRIBUTES The ability to read basic attributes 2138 (non-acls) of a file 2139 WRITE_ATTRIBUTES Permission to change basic attributes 2140 (non-acls) of a file 2142 DELETE Permission to Delete the file 2143 READ_ACL Permission to Read the ACL 2144 WRITE_ACL Permission to Write the ACL 2145 WRITE_OWNER Permission to change the owner 2146 SYNCHRONIZE Permission to access file locally at the 2147 server with synchronous reads and writes 2149 The bitmask constants used for the access mask field are as follows: 2151 const ACE4_READ_DATA = 0x00000001; 2152 const ACE4_LIST_DIRECTORY = 0x00000001; 2153 const ACE4_WRITE_DATA = 0x00000002; 2154 const ACE4_ADD_FILE = 0x00000002; 2155 const ACE4_APPEND_DATA = 0x00000004; 2156 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 2157 const ACE4_READ_NAMED_ATTRS = 0x00000008; 2158 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 2159 const ACE4_EXECUTE = 0x00000020; 2160 const ACE4_DELETE_CHILD = 0x00000040; 2161 const ACE4_READ_ATTRIBUTES = 0x00000080; 2162 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 2164 const ACE4_DELETE = 0x00010000; 2165 const ACE4_READ_ACL = 0x00020000; 2167 Draft Specification NFS version 4 Protocol November 2001 2169 const ACE4_WRITE_ACL = 0x00040000; 2170 const ACE4_WRITE_OWNER = 0x00080000; 2171 const ACE4_SYNCHRONIZE = 0x00100000; 2173 5.9.4. ACE who 2175 There are several special identifiers ("who") which need to be 2176 understood universally. Some of these identifiers cannot be 2177 understood when an NFS client accesses the server, but have meaning 2178 when a local process accesses the file. The ability to display and 2179 modify these permissions is permitted over NFS. 2181 Who Description 2182 _______________________________________________________________ 2183 "OWNER" The owner of the file. 2184 "GROUP" The group associated with the file. 2185 "EVERYONE" The world. 2186 "INTERACTIVE" Accessed from an interactive terminal. 2187 "NETWORK" Accessed via the network. 2188 "DIALUP" Accessed as a dialup user to the server. 2189 "BATCH" Accessed from a batch job. 2190 "ANONYMOUS" Accessed without any authentication. 2191 "AUTHENTICATED" Any authenticated user (opposite of 2192 ANONYMOUS) 2193 "SERVICE" Access from a system service. 2195 To avoid conflict, these special identifiers are distinguish by an 2196 appended "@" and should appear in the form "xxxx@" (note: no domain 2197 name after the "@"). For example: ANONYMOUS@. 2199 Draft Specification NFS version 4 Protocol November 2001 2201 6. File System Migration and Replication 2203 With the use of the recommended attribute "fs_locations", the NFS 2204 version 4 server has a method of providing file system migration or 2205 replication services. For the purposes of migration and replication, 2206 a file system will be defined as all files that share a given fsid 2207 (both major and minor values are the same). 2209 The fs_locations attribute provides a list of file system locations. 2210 These locations are specified by providing the server name (either 2211 DNS domain or IP address) and the path name representing the root of 2212 the file system. Depending on the type of service being provided, 2213 the list will provide a new location or a set of alternate locations 2214 for the file system. The client will use this information to 2215 redirect its requests to the new server. 2217 6.1. Replication 2219 It is expected that file system replication will be used in the case 2220 of read-only data. Typically, the file system will be replicated on 2221 two or more servers. The fs_locations attribute will provide the 2222 list of these locations to the client. On first access of the file 2223 system, the client should obtain the value of the fs_locations 2224 attribute. If, in the future, the client finds the server 2225 unresponsive, the client may attempt to use another server specified 2226 by fs_locations. 2228 If applicable, the client must take the appropriate steps to recover 2229 valid filehandles from the new server. This is described in more 2230 detail in the following sections. 2232 6.2. Migration 2234 File system migration is used to move a file system from one server 2235 to another. Migration is typically used for a file system that is 2236 writable and has a single copy. The expected use of migration is for 2237 load balancing or general resource reallocation. The protocol does 2238 not specify how the file system will be moved between servers. This 2239 server-to-server transfer mechanism is left to the server 2240 implementor. However, the method used to communicate the migration 2241 event between client and server is specified here. 2243 Once the servers participating in the migration have completed the 2244 move of the file system, the error NFS4ERR_MOVED will be returned for 2245 subsequent requests received by the original server. The 2246 NFS4ERR_MOVED error is returned for all operations except GETATTR. 2247 Upon receiving the NFS4ERR_MOVED error, the client will obtain the 2248 value of the fs_locations attribute. The client will then use the 2249 contents of the attribute to redirect its requests to the specified 2250 server. To facilitate the use of GETATTR, operations such as PUTFH 2252 Draft Specification NFS version 4 Protocol November 2001 2254 must also be accepted by the server for the migrated file system's 2255 filehandles. Note that if the server returns NFS4ERR_MOVED, the 2256 server MUST support the fs_locations attribute. 2258 If the client requests more attributes than just fs_locations, the 2259 server may return fs_locations only. This is to be expected since 2260 the server has migrated the file system and may not have a method of 2261 obtaining additional attribute data. 2263 The server implementor needs to be careful in developing a migration 2264 solution. The server must consider all of the state information 2265 clients may have outstanding at the server. This includes but is not 2266 limited to locking/share state, delegation state, and asynchronous 2267 file writes which are represented by WRITE and COMMIT verifiers. The 2268 server should strive to minimize the impact on its clients during and 2269 after the migration process. 2271 6.3. Interpretation of the fs_locations Attribute 2273 The fs_location attribute is structured in the following way: 2275 struct fs_location { 2276 utf8string server<>; 2277 pathname4 rootpath; 2278 }; 2280 struct fs_locations { 2281 pathname4 fs_root; 2282 fs_location locations<>; 2283 }; 2285 The fs_location struct is used to represent the location of a file 2286 system by providing a server name and the path to the root of the 2287 file system. For a multi-homed server or a set of servers that use 2288 the same rootpath, an array of server names may be provided. An 2289 entry in the server array is an UTF8 string and represents one of a 2290 traditional DNS host name, IPv4 address, or IPv6 address. It is not 2291 a requirement that all servers that share the same rootpath be listed 2292 in one fs_location struct. The array of server names is provided for 2293 convenience. Servers that share the same rootpath may also be listed 2294 in separate fs_location entries in the fs_locations attribute. 2296 The fs_locations struct and attribute then contains an array of 2297 locations. Since the name space of each server may be constructed 2298 differently, the "fs_root" field is provided. The path represented 2299 by fs_root represents the location of the file system in the server's 2300 name space. Therefore, the fs_root path is only associated with the 2301 server from which the fs_locations attribute was obtained. The 2302 fs_root path is meant to aid the client in locating the file system 2303 at the various servers listed. 2305 Draft Specification NFS version 4 Protocol November 2001 2307 As an example, there is a replicated file system located at two 2308 servers (servA and servB). At servA the file system is located at 2309 path "/a/b/c". At servB the file system is located at path "/x/y/z". 2310 In this example the client accesses the file system first at servA 2311 with a multi-component lookup path of "/a/b/c/d". Since the client 2312 used a multi-component lookup to obtain the filehandle at "/a/b/c/d", 2313 it is unaware that the file system's root is located in servA's name 2314 space at "/a/b/c". When the client switches to servB, it will need 2315 to determine that the directory it first referenced at servA is now 2316 represented by the path "/x/y/z/d" on servB. To facilitate this, the 2317 fs_locations attribute provided by servA would have a fs_root value 2318 of "/a/b/c" and two entries in fs_location. One entry in fs_location 2319 will be for itself (servA) and the other will be for servB with a 2320 path of "/x/y/z". With this information, the client is able to 2321 substitute "/x/y/z" for the "/a/b/c" at the beginning of its access 2322 path and construct "/x/y/z/d" to use for the new server. 2324 6.4. Filehandle Recovery for Migration or Replication 2326 Filehandles for file systems that are replicated or migrated 2327 generally have the same semantics as for file systems that are not 2328 replicated or migrated. For example, if a file system has persistent 2329 filehandles and it is migrated to another server, the filehandle 2330 values for the file system will be valid at the new server. 2332 For volatile filehandles, the servers involved likely do not have a 2333 mechanism to transfer filehandle format and content between 2334 themselves. Therefore, a server may have difficulty in determining 2335 if a volatile filehandle from an old server should return an error of 2336 NFS4ERR_FHEXPIRED. Therefore, the client is informed, with the use 2337 of the fh_expire_type attribute, whether volatile filehandles will 2338 expire at the migration or replication event. If the bit 2339 FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client 2340 must treat the volatile filehandle as if the server had returned the 2341 NFS4ERR_FHEXPIRED error. At the migration or replication event in 2342 the presence of the FH4_VOL_MIGRATION bit, the client will not 2343 present the original or old volatile file handle to the new server. 2344 The client will start its communication with the new server by 2345 recovering its filehandles using the saved file names. 2347 Draft Specification NFS version 4 Protocol November 2001 2349 7. NFS Server Name Space 2351 7.1. Server Exports 2353 On a UNIX server the name space describes all the files reachable by 2354 pathnames under the root directory or "/". On a Windows NT server 2355 the name space constitutes all the files on disks named by mapped 2356 disk letters. NFS server administrators rarely make the entire 2357 server's file system name space available to NFS clients. More often 2358 portions of the name space are made available via an "export" 2359 feature. In previous versions of the NFS protocol, the root 2360 filehandle for each export is obtained through the MOUNT protocol; 2361 the client sends a string that identifies the export of name space 2362 and the server returns the root filehandle for it. The MOUNT 2363 protocol supports an EXPORTS procedure that will enumerate the 2364 server's exports. 2366 7.2. Browsing Exports 2368 The NFS version 4 protocol provides a root filehandle that clients 2369 can use to obtain filehandles for these exports via a multi-component 2370 LOOKUP. A common user experience is to use a graphical user 2371 interface (perhaps a file "Open" dialog window) to find a file via 2372 progressive browsing through a directory tree. The client must be 2373 able to move from one export to another export via single-component, 2374 progressive LOOKUP operations. 2376 This style of browsing is not well supported by the NFS version 2 and 2377 3 protocols. The client expects all LOOKUP operations to remain 2378 within a single server file system. For example, the device 2379 attribute will not change. This prevents a client from taking name 2380 space paths that span exports. 2382 An automounter on the client can obtain a snapshot of the server's 2383 name space using the EXPORTS procedure of the MOUNT protocol. If it 2384 understands the server's pathname syntax, it can create an image of 2385 the server's name space on the client. The parts of the name space 2386 that are not exported by the server are filled in with a "pseudo file 2387 system" that allows the user to browse from one mounted file system 2388 to another. There is a drawback to this representation of the 2389 server's name space on the client: it is static. If the server 2390 administrator adds a new export the client will be unaware of it. 2392 7.3. Server Pseudo File System 2394 NFS version 4 servers avoid this name space inconsistency by 2395 presenting all the exports within the framework of a single server 2396 name space. An NFS version 4 client uses LOOKUP and READDIR 2397 operations to browse seamlessly from one export to another. Portions 2399 Draft Specification NFS version 4 Protocol November 2001 2401 of the server name space that are not exported are bridged via a 2402 "pseudo file system" that provides a view of exported directories 2403 only. A pseudo file system has a unique fsid and behaves like a 2404 normal, read only file system. 2406 Based on the construction of the server's name space, it is possible 2407 that multiple pseudo file systems may exist. For example, 2409 /a pseudo file system 2410 /a/b real file system 2411 /a/b/c pseudo file system 2412 /a/b/c/d real file system 2414 Each of the pseudo file systems are consider separate entities and 2415 therefore will have a unique fsid. 2417 7.4. Multiple Roots 2419 The DOS and Windows operating environments are sometimes described as 2420 having "multiple roots". File systems are commonly represented as 2421 disk letters. MacOS represents file systems as top level names. NFS 2422 version 4 servers for these platforms can construct a pseudo file 2423 system above these root names so that disk letters or volume names 2424 are simply directory names in the pseudo root. 2426 7.5. Filehandle Volatility 2428 The nature of the server's pseudo file system is that it is a logical 2429 representation of file system(s) available from the server. 2430 Therefore, the pseudo file system is most likely constructed 2431 dynamically when the server is first instantiated. It is expected 2432 that the pseudo file system may not have an on disk counterpart from 2433 which persistent filehandles could be constructed. Even though it is 2434 preferable that the server provide persistent filehandles for the 2435 pseudo file system, the NFS client should expect that pseudo file 2436 system filehandles are volatile. This can be confirmed by checking 2437 the associated "fh_expire_type" attribute for those filehandles in 2438 question. If the filehandles are volatile, the NFS client must be 2439 prepared to recover a filehandle value (e.g. with a multi-component 2440 LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. 2442 7.6. Exported Root 2444 If the server's root file system is exported, one might conclude that 2445 a pseudo-file system is not needed. This would be wrong. Assume the 2446 following file systems on a server: 2448 / disk1 (exported) 2449 /a disk2 (not exported) 2451 Draft Specification NFS version 4 Protocol November 2001 2453 /a/b disk3 (exported) 2455 Because disk2 is not exported, disk3 cannot be reached with simple 2456 LOOKUPs. The server must bridge the gap with a pseudo-file system. 2458 7.7. Mount Point Crossing 2460 The server file system environment may be constructed in such a way 2461 that one file system contains a directory which is 'covered' or 2462 mounted upon by a second file system. For example: 2464 /a/b (file system 1) 2465 /a/b/c/d (file system 2) 2467 The pseudo file system for this server may be constructed to look 2468 like: 2470 / (place holder/not exported) 2471 /a/b (file system 1) 2472 /a/b/c/d (file system 2) 2474 It is the server's responsibility to present the pseudo file system 2475 that is complete to the client. If the client sends a lookup request 2476 for the path "/a/b/c/d", the server's response is the filehandle of 2477 the file system "/a/b/c/d". In previous versions of the NFS 2478 protocol, the server would respond with the directory "/a/b/c/d" 2479 within the file system "/a/b". 2481 The NFS client will be able to determine if it crosses a server mount 2482 point by a change in the value of the "fsid" attribute. 2484 7.8. Security Policy and Name Space Presentation 2486 The application of the server's security policy needs to be carefully 2487 considered by the implementor. One may choose to limit the 2488 viewability of portions of the pseudo file system based on the 2489 server's perception of the client's ability to authenticate itself 2490 properly. However, with the support of multiple security mechanisms 2491 and the ability to negotiate the appropriate use of these mechanisms, 2492 the server is unable to properly determine if a client will be able 2493 to authenticate itself. If, based on its policies, the server 2494 chooses to limit the contents of the pseudo file system, the server 2495 may effectively hide file systems from a client that may otherwise 2496 have legitimate access. 2498 Draft Specification NFS version 4 Protocol November 2001 2500 8. File Locking and Share Reservations 2502 Integrating locking into the NFS protocol necessarily causes it to be 2503 state-full. With the inclusion of "share" file locks the protocol 2504 becomes substantially more dependent on state than the traditional 2505 combination of NFS and NLM [XNFS]. There are three components to 2506 making this state manageable: 2508 o Clear division between client and server 2510 o Ability to reliably detect inconsistency in state between client 2511 and server 2513 o Simple and robust recovery mechanisms 2515 In this model, the server owns the state information. The client 2516 communicates its view of this state to the server as needed. The 2517 client is also able to detect inconsistent state before modifying a 2518 file. 2520 To support Win32 "share" locks it is necessary to atomically OPEN or 2521 CREATE files. Having a separate share/unshare operation would not 2522 allow correct implementation of the Win32 OpenFile API. In order to 2523 correctly implement share semantics, the previous NFS protocol 2524 mechanisms used when a file is opened or created (LOOKUP, CREATE, 2525 ACCESS) need to be replaced. The NFS version 4 protocol has an OPEN 2526 operation that subsumes the functionality of LOOKUP, CREATE, and 2527 ACCESS. However, because many operations require a filehandle, the 2528 traditional LOOKUP is preserved to map a file name to filehandle 2529 without establishing state on the server. The policy of granting 2530 access or modifying files is managed by the server based on the 2531 client's state. These mechanisms can implement policy ranging from 2532 advisory only locking to full mandatory locking. 2534 8.1. Locking 2536 It is assumed that manipulating a lock is rare when compared to READ 2537 and WRITE operations. It is also assumed that crashes and network 2538 partitions are relatively rare. Therefore it is important that the 2539 READ and WRITE operations have a lightweight mechanism to indicate if 2540 they possess a held lock. A lock request contains the heavyweight 2541 information required to establish a lock and uniquely define the lock 2542 owner. 2544 The following sections describe the transition from the heavy weight 2545 information to the eventual stateid used for most client and server 2546 locking and lease interactions. 2548 8.1.1. Client ID 2550 For each LOCK request, the client must identify itself to the server. 2552 Draft Specification NFS version 4 Protocol November 2001 2554 This is done in such a way as to allow for correct lock 2555 identification and crash recovery. Client identification is 2556 accomplished with two values. 2558 o A verifier that is used to detect client reboots. 2560 o A variable length opaque array to uniquely define a client. 2562 For an operating system this may be a fully qualified host 2563 name or IP address. For a user level NFS client it may 2564 additionally contain a process id or other unique sequence. 2566 The data structure for the Client ID would then appear as: 2568 struct nfs_client_id { 2569 opaque verifier[4]; 2570 opaque id<>; 2571 } 2573 It is possible through the mis-configuration of a client or the 2574 existence of a rogue client that two clients end up using the same 2575 nfs_client_id. This situation is avoided by "negotiating" the 2576 nfs_client_id between client and server with the use of the 2577 SETCLIENTID and SETCLIENTID_CONFIRM operations. The following 2578 describes the two scenarios of negotiation. 2580 1 Client has never connected to the server 2582 In this case the client generates an nfs_client_id and 2583 unless another client has the same nfs_client_id.id field, 2584 the server accepts the request. The server also records the 2585 principal (or principal to uid mapping) from the credential 2586 in the RPC request that contains the nfs_client_id 2587 negotiation request (SETCLIENTID operation). 2589 Two clients might still use the same nfs_client_id.id due 2590 to perhaps configuration error. For example, a High 2591 Availability configuration where the nfs_client_id.id is 2592 derived from the ethernet controller address and both 2593 systems have the same address. In this case, the result is 2594 a switched union that returns, in addition to 2595 NFS4ERR_CLID_INUSE, the network address (the rpcbind netid 2596 and universal address) of the client that is using the id. 2598 2 Client is re-connecting to the server after a client reboot 2600 In this case, the client still generates an nfs_client_id 2601 but the nfs_client_id.id field will be the same as the 2602 nfs_client_id.id generated prior to reboot. If the server 2603 finds that the principal/uid is equal to the previously 2604 "registered" nfs_client_id.id, then locks associated with 2606 Draft Specification NFS version 4 Protocol November 2001 2608 the old nfs_client_id are immediately released. If the 2609 principal/uid is not equal, then this is a rogue client and 2610 the request is returned in error. For more discussion of 2611 crash recovery semantics, see the section on "Crash 2612 Recovery". 2614 It is possible for a retransmission of request to be 2615 received by the server after the server has acted upon and 2616 responded to the original client request. Therefore to 2617 mitigate effects of the retransmission of the SETCLIENTID 2618 operation, the client and server use a confirmation step. 2619 The server returns a confirmation verifier that the client 2620 then sends to the server in the SETCLIENTID_CONFIRM 2621 operation. Once the server receives the confirmation from 2622 the client, the locking state for the client is released. 2624 In both cases, upon success, NFS4_OK is returned. To help reduce the 2625 amount of data transferred on OPEN and LOCK, the server will also 2626 return a unique 64-bit clientid value that is a shorthand reference 2627 to the nfs_client_id values presented by the client. From this point 2628 forward, the client will use the clientid to refer to itself. 2630 The clientid assigned by the server should be chosen so that it will 2631 not conflict with a clientid previously assigned by the server. This 2632 applies across server restarts or reboots. When a clientid is 2633 presented to a server and that clientid is not recognized, as would 2634 happen after a server reboot, the server will reject the request with 2635 the error NFS4ERR_STALE_CLIENTID. When this happens, the client must 2636 obtain a new clientid by use of the SETCLIENTID operation and then 2637 proceed to any other necessary recovery for the server reboot case 2638 (See the section "Server Failure and Recovery"). 2640 The client must also employ the SETCLIENTID operation when it 2641 receives a NFS4ERR_STALE_STATEID error using a stateid derived from 2642 its current clientid, since this also indicates a server reboot which 2643 has invalidated the existing clientid (see the next section 2644 "nfs_lockowner and stateid Definition" for details). 2646 8.1.2. Server Release of Clientid 2648 If the server determines that the client holds no associated state 2649 for its clientid, the server may choose to release the clientid. The 2650 server may make this choice for an inactive client so that resources 2651 are not consumed by those intermittently active clients. If the 2652 client contacts the server after this release, the server must ensure 2653 the client receives the appropriate error so that it will use the 2654 SETCLIENTID/SETCLIENTID_CONFIRM sequence to establish a new identity. 2655 It should be clear that the server must be very hesitant to release a 2656 clientid since the resulting work on the client to recover from such 2657 an event will be the same burden as if the server had failed and 2658 restarted. Typically a server would not release a clientid unless 2660 Draft Specification NFS version 4 Protocol November 2001 2662 there had been no activity from that client for many minutes. 2664 8.1.3. nfs_lockowner and stateid Definition 2666 When requesting a lock, the client must present to the server the 2667 clientid and an identifier for the owner of the requested lock. 2668 These two fields are referred to as the nfs_lockowner and the 2669 definition of those fields are: 2671 o A clientid returned by the server as part of the client's use of 2672 the SETCLIENTID operation. 2674 o A variable length opaque array used to uniquely define the owner 2675 of a lock managed by the client. 2677 This may be a thread id, process id, or other unique value. 2679 When the server grants the lock, it responds with a unique 64-bit 2680 stateid. The stateid is used as a shorthand reference to the 2681 nfs_lockowner, since the server will be maintaining the 2682 correspondence between them. 2684 The server is free to form the stateid in any manner that it chooses 2685 as long as it is able to recognize invalid and out-of-date stateids. 2686 This requirement includes those stateids generated by earlier 2687 instances of the server. From this, the client can be properly 2688 notified of a server restart. This notification will occur when the 2689 client presents a stateid to the server from a previous 2690 instantiation. 2692 The server must be able to distinguish the following situations and 2693 return the error as specified: 2695 o The stateid was generated by an earlier server instance (i.e. 2696 before a server reboot). The error NFS4ERR_STALE_STATEID should 2697 be returned. 2699 o The stateid was generated by the current server instance but the 2700 stateid no longer designates the current locking state for the 2701 lockowner-file pair in question (i.e. one or more locking 2702 operations has occurred). The error NFS4ERR_OLD_STATEID should 2703 be returned. 2705 This error condition will only occur when the client issues a 2706 locking request which changes a stateid while an I/O request 2707 that uses that stateid is outstanding. 2709 o The stateid was generated by the current server instance but the 2710 stateid does not designate a locking state for any active 2711 lockowner-file pair. The error NFS4ERR_BAD_STATEID should be 2713 Draft Specification NFS version 4 Protocol November 2001 2715 returned. 2717 This error condition will occur when there has been a logic 2718 error on the part of the client or server. This should not 2719 happen. 2721 One mechanism that may be used to satisfy these requirements is for 2722 the server to divide stateids into three fields: 2724 o A server verifier which uniquely designates a particular server 2725 instantiation. 2727 o An index into a table of locking-state structures. 2729 o A sequence value which is incremented for each stateid that is 2730 associated with the same index into the locking-state table. 2732 By matching the incoming stateid and its field values with the state 2733 held at the server, the server is able to easily determine if a 2734 stateid is valid for its current instantiation and state. If the 2735 stateid is not valid, the appropriate error can be supplied to the 2736 client. 2738 8.1.4. Use of the stateid 2740 All READ and WRITE operations contain a stateid. If the 2741 nfs_lockowner performs a READ or WRITE on a range of bytes within a 2742 locked range, the stateid (previously returned by the server) must be 2743 used to indicate that the appropriate lock (record or share) is held. 2744 If no state is established by the client, either record lock or share 2745 lock, a stateid of all bits 0 is used. If no conflicting locks are 2746 held on the file, the server may service the READ or WRITE operation. 2747 If a conflict with an explicit lock occurs, an error is returned for 2748 the operation (NFS4ERR_LOCKED). This allows "mandatory locking" to be 2749 implemented. 2751 A stateid of all bits 1 (one) allows READ operations to bypass record 2752 locking checks at the server. However, WRITE operations with stateid 2753 with bits all 1 (one) do not bypass record locking checks. File 2754 locking checks are handled by the OPEN operation (see the section 2755 "OPEN/CLOSE Operations"). 2757 An explicit lock may not be granted while a READ or WRITE operation 2758 with conflicting implicit locking is being performed. 2760 8.1.5. Sequencing of Lock Requests 2762 Locking is different than most NFS operations as it requires "at- 2763 most-one" semantics that are not provided by ONCRPC. ONCRPC over a 2765 Draft Specification NFS version 4 Protocol November 2001 2767 reliable transport is not sufficient because a sequence of locking 2768 requests may span multiple TCP connections. In the face of 2769 retransmission or reordering, lock or unlock requests must have a 2770 well defined and consistent behavior. To accomplish this, each lock 2771 request contains a sequence number that is a consecutively increasing 2772 integer. Different nfs_lockowners have different sequences. The 2773 server maintains the last sequence number (L) received and the 2774 response that was returned. 2776 Note that for requests that contain a sequence number, for each 2777 nfs_lockowner, there should be no more than one outstanding request. 2779 If a request with a previous sequence number (r < L) is received, it 2780 is rejected with the return of error NFS4ERR_BAD_SEQID. Given a 2781 properly-functioning client, the response to (r) must have been 2782 received before the last request (L) was sent. If a duplicate of 2783 last request (r == L) is received, the stored response is returned. 2784 If a request beyond the next sequence (r == L + 2) is received, it is 2785 rejected with the return of error NFS4ERR_BAD_SEQID. Sequence 2786 history is reinitialized whenever the client verifier changes. 2788 Since the sequence number is represented with an unsigned 32-bit 2789 integer, the arithmetic involved with the sequence number is mod 2790 2^32. 2792 It is critical the server maintain the last response sent to the 2793 client to provide a more reliable cache of duplicate non-idempotent 2794 requests than that of the traditional cache described in [Juszczak]. 2795 The traditional duplicate request cache uses a least recently used 2796 algorithm for removing unneeded requests. However, the last lock 2797 request and response on a given nfs_lockowner must be cached as long 2798 as the lock state exists on the server. 2800 8.1.6. Recovery from Replayed Requests 2802 As described above, the sequence number is per nfs_lockowner. As 2803 long as the server maintains the last sequence number received and 2804 follows the methods described above, there are no risks of a 2805 Byzantine router re-sending old requests. The server need only 2806 maintain the nfs_lockowner, sequence number state as long as there 2807 are open files or closed files with locks outstanding. 2809 LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence 2810 number and therefore the risk of the replay of these operations 2811 resulting in undesired effects is non-existent while the server 2812 maintains the nfs_lockowner state. 2814 8.1.7. Releasing nfs_lockowner State 2816 When a particular nfs_lockowner no longer holds open or file locking 2818 Draft Specification NFS version 4 Protocol November 2001 2820 state at the server, the server may choose to release the sequence 2821 number state associated with the nfs_lockowner. The server may make 2822 this choice based on lease expiration, for the reclamation of server 2823 memory, or other implementation specific details. In any event, the 2824 server is able to do this safely only when the nfs_lockowner no 2825 longer is being utilized by the client. The server may choose to 2826 hold the nfs_lockowner state in the event that retransmitted requests 2827 are received. However, the period to hold this state is 2828 implementation specific. 2830 In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is 2831 retransmitted after the server has previously released the 2832 nfs_lockowner state, the server will find that the nfs_lockowner has 2833 no files open and an error will be returned to the client. If the 2834 nfs_lockowner does have a file open, the stateid will not match and 2835 again an error is returned to the client. 2837 In the case that an OPEN is retransmitted and the nfs_lockowner is 2838 being used for the first time or the nfs_lockowner state has been 2839 previously released by the server, the use of the OPEN_CONFIRM 2840 operation will prevent incorrect behavior. When the server observes 2841 the use of the nfs_lockowner for the first time, it will direct the 2842 client to perform the OPEN_CONFIRM for the corresponding OPEN. This 2843 sequence establishes the use of an nfs_lockowner and associated 2844 sequence number. See the section "OPEN_CONFIRM - Confirm Open" for 2845 further details. 2847 8.2. Lock Ranges 2849 The protocol allows a lock owner to request a lock with one byte 2850 range and then either upgrade or unlock a sub-range of the initial 2851 lock. It is expected that this will be an uncommon type of request. 2852 In any case, servers or server file systems may not be able to 2853 support sub-range lock semantics. In the event that a server 2854 receives a locking request that represents a sub-range of current 2855 locking state for the lock owner, the server is allowed to return the 2856 error NFS4ERR_LOCK_RANGE to signify that it does not support sub- 2857 range lock operations. Therefore, the client should be prepared to 2858 receive this error and, if appropriate, report the error to the 2859 requesting application. 2861 The client is discouraged from combining multiple independent locking 2862 ranges that happen to be adjacent into a single request since the 2863 server may not support sub-range requests and for reasons related to 2864 the recovery of file locking state in the event of server failure. 2865 As discussed in the section "Server Failure and Recovery" below, the 2866 server may employ certain optimizations during recovery that work 2867 effectively only when the client's behavior during lock recovery is 2868 similar to the client's locking behavior prior to server failure. 2870 Draft Specification NFS version 4 Protocol November 2001 2872 8.3. Blocking Locks 2874 Some clients require the support of blocking locks. The NFS version 2875 4 protocol must not rely on a callback mechanism and therefore is 2876 unable to notify a client when a previously denied lock has been 2877 granted. Clients have no choice but to continually poll for the 2878 lock. This presents a fairness problem. Two new lock types are 2879 added, READW and WRITEW, and are used to indicate to the server that 2880 the client is requesting a blocking lock. The server should maintain 2881 an ordered list of pending blocking locks. When the conflicting lock 2882 is released, the server may wait the lease period for the first 2883 waiting client to re-request the lock. After the lease period 2884 expires the next waiting client request is allowed the lock. Clients 2885 are required to poll at an interval sufficiently small that it is 2886 likely to acquire the lock in a timely manner. The server is not 2887 required to maintain a list of pending blocked locks as it is used to 2888 increase fairness and not correct operation. Because of the 2889 unordered nature of crash recovery, storing of lock state to stable 2890 storage would be required to guarantee ordered granting of blocking 2891 locks. 2893 Servers may also note the lock types and delay returning denial of 2894 the request to allow extra time for a conflicting lock to be 2895 released, allowing a successful return. In this way, clients can 2896 avoid the burden of needlessly frequent polling for blocking locks. 2897 The server should take care in the length of delay in the event the 2898 client retransmits the request. 2900 8.4. Lease Renewal 2902 The purpose of a lease is to allow a server to remove stale locks 2903 that are held by a client that has crashed or is otherwise 2904 unreachable. It is not a mechanism for cache consistency and lease 2905 renewals may not be denied if the lease interval has not expired. 2907 The following events cause implicit renewal of all of the leases for 2908 a given client (i.e. all those sharing a given clientid). Each of 2909 these is a positive indication that the client is still active and 2910 that the associated state held at the server, for the client, is 2911 still valid. 2913 o An OPEN with a valid clientid. 2915 o Any operation made with a valid stateid (CLOSE, DELEGRETURN, 2916 LOCK, LOCKU, OPEN, OPEN_CONFIRM, READ, RENEW, SETATTR, WRITE). 2917 This does not include the special stateids of all bits 0 or all 2918 bits 1. 2920 Note that if the client had restarted or rebooted, the 2921 client would not be making these requests without issuing 2922 the SETCLIENTID operation. The use of the SETCLIENTID 2924 Draft Specification NFS version 4 Protocol November 2001 2926 operation (possibly with the addition of the optional 2927 SETCLIENTID_CONFIRM operation) notifies the server to drop 2928 the locking state associated with the client. 2930 If the server has rebooted, the stateids 2931 (NFS4ERR_STALE_STATEID error) or the clientid 2932 (NFS4ERR_STALE_CLIENTID error) will not be valid hence 2933 preventing spurious renewals. 2935 This approach allows for low overhead lease renewal which scales 2936 well. In the typical case no extra RPC calls are required for lease 2937 renewal and in the worst case one RPC is required every lease period 2938 (i.e. a RENEW operation). The number of locks held by the client is 2939 not a factor since all state for the client is involved with the 2940 lease renewal action. 2942 Since all operations that create a new lease also renew existing 2943 leases, the server must maintain a common lease expiration time for 2944 all valid leases for a given client. This lease time can then be 2945 easily updated upon implicit lease renewal actions. 2947 8.5. Crash Recovery 2949 The important requirement in crash recovery is that both the client 2950 and the server know when the other has failed. Additionally, it is 2951 required that a client sees a consistent view of data across server 2952 restarts or reboots. All READ and WRITE operations that may have 2953 been queued within the client or network buffers must wait until the 2954 client has successfully recovered the locks protecting the READ and 2955 WRITE operations. 2957 8.5.1. Client Failure and Recovery 2959 In the event that a client fails, the server may recover the client's 2960 locks when the associated leases have expired. Conflicting locks 2961 from another client may only be granted after this lease expiration. 2962 If the client is able to restart or reinitialize within the lease 2963 period the client may be forced to wait the remainder of the lease 2964 period before obtaining new locks. 2966 To minimize client delay upon restart, lock requests are associated 2967 with an instance of the client by a client supplied verifier. This 2968 verifier is part of the initial SETCLIENTID call made by the client. 2969 The server returns a clientid as a result of the SETCLIENTID 2970 operation. The client then confirms the use of the verifier with 2971 SETCLIENTID_CONFIRM. The clientid in combination with an opaque 2972 owner field is then used by the client to identify the lock owner for 2973 OPEN. This chain of associations is then used to identify all locks 2974 for a particular client. 2976 Draft Specification NFS version 4 Protocol November 2001 2978 Since the verifier will be changed by the client upon each 2979 initialization, the server can compare a new verifier to the verifier 2980 associated with currently held locks and determine that they do not 2981 match. This signifies the client's new instantiation and subsequent 2982 loss of locking state. As a result, the server is free to release 2983 all locks held which are associated with the old clientid which was 2984 derived from the old verifier. 2986 For secure environments, a change in the verifier must only cause the 2987 release of locks associated with the authenticated requester. This 2988 is required to prevent a rogue entity from freeing otherwise valid 2989 locks. 2991 Note that the verifier must have the same uniqueness properties of 2992 the verifier for the COMMIT operation. 2994 8.5.2. Server Failure and Recovery 2996 If the server loses locking state (usually as a result of a restart 2997 or reboot), it must allow clients time to discover this fact and re- 2998 establish the lost locking state. The client must be able to re- 2999 establish the locking state without having the server deny valid 3000 requests because the server has granted conflicting access to another 3001 client. Likewise, if there is the possibility that clients have not 3002 yet re-established their locking state for a file, the server must 3003 disallow READ and WRITE operations for that file. The duration of 3004 this recovery period is equal to the duration of the lease period. 3006 A client can determine that server failure (and thus loss of locking 3007 state) has occurred, when it receives one of two errors. The 3008 NFS4ERR_STALE_STATEID error indicates a stateid invalidated by a 3009 reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a 3010 clientid invalidated by reboot or restart. When either of these are 3011 received, the client must establish a new clientid (See the section 3012 "Client ID") and re-establish the locking state as discussed below. 3014 The period of special handling of locking and READs and WRITEs, equal 3015 in duration to the lease period, is referred to as the "grace 3016 period". During the grace period, clients recover locks and the 3017 associated state by reclaim-type locking requests (i.e. LOCK requests 3018 with reclaim set to true and OPEN operations with a claim type of 3019 CLAIM_PREVIOUS). During the grace period, the server must reject 3020 READ and WRITE operations and non-reclaim locking requests (i.e. 3021 other LOCK and OPEN operations) with an error of NFS4ERR_GRACE. 3023 If the server can reliably determine that granting a non-reclaim 3024 request will not conflict with reclamation of locks by other clients, 3025 the NFS4ERR_GRACE error does not have to be returned and the non- 3026 reclaim client request can be serviced. For the server to be able to 3027 service READ and WRITE operations during the grace period, it must 3028 again be able to guarantee that no possible conflict could arise 3030 Draft Specification NFS version 4 Protocol November 2001 3032 between an impending reclaim locking request and the READ or WRITE 3033 operation. If the server is unable to offer that guarantee, the 3034 NFS4ERR_GRACE error must be returned to the client. 3036 For a server to provide simple, valid handling during the grace 3037 period, the easiest method is to simply reject all non-reclaim 3038 locking requests and READ and WRITE operations by returning the 3039 NFS4ERR_GRACE error. However, a server may keep information about 3040 granted locks in stable storage. With this information, the server 3041 could determine if a regular lock or READ or WRITE operation can be 3042 safely processed. 3044 For example, if a count of locks on a given file is available in 3045 stable storage, the server can track reclaimed locks for the file and 3046 when all reclaims have been processed, non-reclaim locking requests 3047 may be processed. This way the server can ensure that non-reclaim 3048 locking requests will not conflict with potential reclaim requests. 3049 With respect to I/O requests, if the server is able to determine that 3050 there are no outstanding reclaim requests for a file by information 3051 from stable storage or another similar mechanism, the processing of 3052 I/O requests could proceed normally for the file. 3054 To reiterate, for a server that allows non-reclaim lock and I/O 3055 requests to be processed during the grace period, it MUST determine 3056 that no lock subsequently reclaimed will be rejected and that no lock 3057 subsequently reclaimed would have prevented any I/O operation 3058 processed during the grace period. 3060 Clients should be prepared for the return of NFS4ERR_GRACE errors for 3061 non-reclaim lock and I/O requests. In this case the client should 3062 employ a retry mechanism for the request. A delay (on the order of 3063 several seconds) between retries should be used to avoid overwhelming 3064 the server. Further discussion of the general is included in 3065 [Floyd]. The client must account for the server that is able to 3066 perform I/O and non-reclaim locking requests within the grace period 3067 as well as those that can not do so. 3069 A reclaim-type locking request outside the server's grace period can 3070 only succeed if the server can guarantee that no conflicting lock or 3071 I/O request has been granted since reboot or restart. 3073 8.5.3. Network Partitions and Recovery 3075 If the duration of a network partition is greater than the lease 3076 period provided by the server, the server will have not received a 3077 lease renewal from the client. If this occurs, the server may free 3078 all locks held for the client. As a result, all stateids held by the 3079 client will become invalid or stale. Once the client is able to 3080 reach the server after such a network partition, all I/O submitted by 3081 the client with the now invalid stateids will fail with the server 3082 returning the error NFS4ERR_EXPIRED. Once this error is received, 3084 Draft Specification NFS version 4 Protocol November 2001 3086 the client will suitably notify the application that held the lock. 3088 As a courtesy to the client or as an optimization, the server may 3089 continue to hold locks on behalf of a client for which recent 3090 communication has extended beyond the lease period. If the server 3091 receives a lock or I/O request that conflicts with one of these 3092 courtesy locks, the server must free the courtesy lock and grant the 3093 new request. 3095 If the server continues to hold locks beyond the expiration of a 3096 client's lease, the server MUST employ a method of recording this 3097 fact in its stable storage. Conflicting locks requests from another 3098 client may be serviced after the lease expiration. There are various 3099 scenarios involving server failure after such an event that require 3100 the storage of these lease expirations or network partitions. One 3101 scenario is as follows: 3103 A client holds a lock at the server and encounters a 3104 network partition and is unable to renew the associated 3105 lease. A second client obtains a conflicting lock and then 3106 frees the lock. After the unlock request by the second 3107 client, the server reboots or reinitializes. Once the 3108 server recovers, the network partition heals and the 3109 original client attempts to reclaim the original lock. 3111 In this scenario and without any state information, the server will 3112 allow the reclaim and the client will be in an inconsistent state 3113 because the server or the client has no knowledge of the conflicting 3114 lock. 3116 The server may choose to store this lease expiration or network 3117 partitioning state in a way that will only identify the client as a 3118 whole. Note that this may potentially lead to lock reclaims being 3119 denied unnecessarily because of a mix of conflicting and non- 3120 conflicting locks. The server may also choose to store information 3121 about each lock that has an expired lease with an associated 3122 conflicting lock. The choice of the amount and type of state 3123 information that is stored is left to the implementor. In any case, 3124 the server must have enough state information to enable correct 3125 recovery from multiple partitions and multiple server failures. 3127 8.6. Recovery from a Lock Request Timeout or Abort 3129 In the event a lock request times out, a client may decide to not 3130 retry the request. The client may also abort the request when the 3131 process for which it was issued is terminated (e.g. in UNIX due to a 3132 signal. It is possible though that the server received the request 3133 and acted upon it. This would change the state on the server without 3134 the client being aware of the change. It is paramount that the 3135 client re-synchronize state with server before it attempts any other 3137 Draft Specification NFS version 4 Protocol November 2001 3139 operation that takes a seqid and/or a stateid with the same 3140 nfs_lockowner. This is straightforward to do without a special re- 3141 synchronize operation. 3143 Since the server maintains the last lock request and response 3144 received on the nfs_lockowner, for each nfs_lockowner, the client 3145 should cache the last lock request it sent such that the lock request 3146 did not receive a response. From this, the next time the client does 3147 a lock operation for the nfs_lockowner, it can send the cached 3148 request, if there is one, and if the request was one that established 3149 state (e.g. a LOCK or OPEN operation) the client can follow up with a 3150 request to remove the state (e.g. a LOCKU or CLOSE operation). With 3151 this approach, the sequencing and stateid information on the client 3152 and server for the given nfs_lockowner will re-synchronize and in 3153 turn the lock state will re-synchronize. 3155 8.7. Server Revocation of Locks 3157 At any point, the server can revoke locks held by a client and the 3158 client must be prepared for this event. When the client detects that 3159 its locks have been or may have been revoked, the client is 3160 responsible for validating the state information between itself and 3161 the server. Validating locking state for the client means that it 3162 must verify or reclaim state for each lock currently held. 3164 The first instance of lock revocation is upon server reboot or re- 3165 initialization. In this instance the client will receive an error 3166 (NFS4ERR_STALE_STATEID or NFS4ERR_STALE_CLIENTID) and the client will 3167 proceed with normal crash recovery as described in the previous 3168 section. 3170 The second lock revocation event is the inability to renew the lease 3171 period. While this is considered a rare or unusual event, the client 3172 must be prepared to recover. Both the server and client will be able 3173 to detect the failure to renew the lease and are capable of 3174 recovering without data corruption. For the server, it tracks the 3175 last renewal event serviced for the client and knows when the lease 3176 will expire. Similarly, the client must track operations which will 3177 renew the lease period. Using the time that each such request was 3178 sent and the time that the corresponding reply was received, the 3179 client should bound the time that the corresponding renewal could 3180 have occurred on the server and thus determine if it is possible that 3181 a lease period expiration could have occurred. 3183 The third lock revocation event can occur as a result of 3184 administrative intervention within the lease period. While this is 3185 considered a rare event, it is possible that the server's 3186 administrator has decided to release or revoke a particular lock held 3187 by the client. As a result of revocation, the client will receive an 3188 error of NFS4ERR_EXPIRED and the error is received within the lease 3189 period for the lock. In this instance the client may assume that 3191 Draft Specification NFS version 4 Protocol November 2001 3193 only the nfs_lockowner's locks have been lost. The client notifies 3194 the lock holder appropriately. The client may not assume the lease 3195 period has been renewed as a result of failed operation. 3197 When the client determines the lease period may have expired, the 3198 client must mark all locks held for the associated lease as 3199 "unvalidated". This means the client has been unable to re-establish 3200 or confirm the appropriate lock state with the server. As described 3201 in the previous section on crash recovery, there are scenarios in 3202 which the server may grant conflicting locks after the lease period 3203 has expired for a client. When it is possible that the lease period 3204 has expired, the client must validate each lock currently held to 3205 ensure that a conflicting lock has not been granted. The client may 3206 accomplish this task by issuing an I/O request, either a pending I/O 3207 or a zero-length read, specifying the stateid associated with the 3208 lock in question. If the response to the request is success, the 3209 client has validated all of the locks governed by that stateid and 3210 re-established the appropriate state between itself and the server. 3211 If the I/O request is not successful, then one or more of the locks 3212 associated with the stateid was revoked by the server and the client 3213 must notify the owner. 3215 8.8. Share Reservations 3217 A share reservation is a mechanism to control access to a file. It 3218 is a separate and independent mechanism from record locking. When a 3219 client opens a file, it issues an OPEN operation to the server 3220 specifying the type of access required (READ, WRITE, or BOTH) and the 3221 type of access to deny others (deny NONE, READ, WRITE, or BOTH). If 3222 the OPEN fails the client will fail the application's open request. 3224 Pseudo-code definition of the semantics: 3226 if ((request.access & file_state.deny)) || 3227 (request.deny & file_state.access)) 3228 return (NFS4ERR_DENIED) 3230 The constants used for the OPEN and OPEN_DOWNGRADE operations for the 3231 access and deny fields are as follows: 3233 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 3234 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 3235 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 3237 const OPEN4_SHARE_DENY_NONE = 0x00000000; 3238 const OPEN4_SHARE_DENY_READ = 0x00000001; 3239 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 3240 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 3242 Draft Specification NFS version 4 Protocol November 2001 3244 8.9. OPEN/CLOSE Operations 3246 To provide correct share semantics, a client MUST use the OPEN 3247 operation to obtain the initial filehandle and indicate the desired 3248 access and what if any access to deny. Even if the client intends to 3249 use a stateid of all 0's or all 1's, it must still obtain the 3250 filehandle for the regular file with the OPEN operation so the 3251 appropriate share semantics can be applied. For clients that do not 3252 have a deny mode built into their open programming interfaces, deny 3253 equal to NONE should be used. 3255 The OPEN operation with the CREATE flag, also subsumes the CREATE 3256 operation for regular files as used in previous versions of the NFS 3257 protocol. This allows a create with a share to be done atomically. 3259 The CLOSE operation removes all share locks held by the nfs_lockowner 3260 on that file. If record locks are held, the client SHOULD release 3261 all locks before issuing a CLOSE. The server MAY free all 3262 outstanding locks on CLOSE but some servers may not support the CLOSE 3263 of a file that still has record locks held. The server MUST return 3264 failure if any locks would exist after the CLOSE. 3266 The LOOKUP operation will return a filehandle without establishing 3267 any lock state on the server. Without a valid stateid, the server 3268 will assume the client has the least access. For example, a file 3269 opened with deny READ/WRITE cannot be accessed using a filehandle 3270 obtained through LOOKUP because it would not have a valid stateid 3271 (i.e. using a stateid of all bits 0 or all bits 1). 3273 8.10. Open Upgrade and Downgrade 3275 When an OPEN is done for a file and the lockowner for which the open 3276 is being done already has the file open, the result is to upgrade the 3277 open file status maintained on the server to include the access and 3278 deny bits specified by the new OPEN as well as those for the existing 3279 OPEN. The result is that there is one open file, as far as the 3280 protocol is concerned, and it includes the union of the access and 3281 deny bits for all of the OPEN requests completed. Only a single 3282 CLOSE will be done to reset the effects of both OPEN's. Note that 3283 the client, when issuing the OPEN, may not know that the same file is 3284 in fact being opened. The above only applies if both OPEN's result 3285 in the OPEN'ed object being designated by the same filehandle. 3287 When the server chooses to export multiple filehandles corresponding 3288 to the same file object and returns different filehandles on two 3289 different OPEN's of the same file object, the server MUST NOT "OR" 3290 together the access and deny bits and coalesce the two open files. 3291 Instead the server must maintain separate OPEN's with separate 3292 stateid's and will require separate CLOSE's to free them. 3294 When multiple open files on the client are merged into a single open 3296 Draft Specification NFS version 4 Protocol November 2001 3298 file object on the server, the close of one of the open files (on the 3299 client) may necessitate change of the access and deny status of the 3300 open file on the server. This is because the union of the access and 3301 deny bits for the remaining open's may be smaller (i.e. a proper 3302 subset) than previously. The OPEN_DOWNGRADE operation is used to 3303 make the necessary change and the client should use it to update the 3304 server so that share reservation requests by other clients are 3305 handled properly. 3307 8.11. Short and Long Leases 3309 When determining the time period for the server lease, the usual 3310 lease tradeoffs apply. Short leases are good for fast server 3311 recovery at a cost of increased RENEW or READ (with zero length) 3312 requests. Longer leases are certainly kinder and gentler to large 3313 internet servers trying to handle very large numbers of clients. The 3314 number of RENEW requests drop in proportion to the lease time. The 3315 disadvantages of long leases are slower recovery after server failure 3316 (server must wait for leases to expire and grace period before 3317 granting new lock requests) and increased file contention (if client 3318 fails to transmit an unlock request then server must wait for lease 3319 expiration before granting new locks). 3321 Long leases are usable if the server is able to store lease state in 3322 non-volatile memory. Upon recovery, the server can reconstruct the 3323 lease state from its non-volatile memory and continue operation with 3324 its clients and therefore long leases are not an issue. 3326 8.12. Clocks and Calculating Lease Expiration 3328 To avoid the need for synchronized clocks, lease times are granted by 3329 the server as a time delta. However, there is a requirement that the 3330 client and server clocks do not drift excessively over the duration 3331 of the lock. There is also the issue of propagation delay across the 3332 network which could easily be several hundred milliseconds as well as 3333 the possibility that requests will be lost and need to be 3334 retransmitted. 3336 To take propagation delay into account, the client should subtract it 3337 from lease times (e.g. if the client estimates the one-way 3338 propagation delay as 200 msec, then it can assume that the lease is 3339 already 200 msec old when it gets it). In addition, it will take 3340 another 200 msec to get a response back to the server. So the client 3341 must send a lock renewal or write data back to the server 400 msec 3342 before the lease would expire. 3344 Draft Specification NFS version 4 Protocol November 2001 3346 8.13. Migration, Replication and State 3348 When responsibility for handling a given file system is transferred 3349 to a new server (migration) or the client chooses to use an alternate 3350 server (e.g. in response to server unresponsiveness) in the context 3351 of file system replication, the appropriate handling of state shared 3352 between the client and server (i.e. locks, leases, stateid's, and 3353 clientid's) is as described below. The handling differs between 3354 migration and replication. For related discussion of file server 3355 state and recover of such see the sections under "File Locking and 3356 Share Reservations" 3358 8.13.1. Migration and State 3360 In the case of migration, the servers involved in the migration of a 3361 file system SHOULD transfer all server state from the original to the 3362 new server. This must be done in a way that is transparent to the 3363 client. This state transfer will ease the client's transition when a 3364 file system migration occurs. If the servers are successful in 3365 transferring all state, the client will continue to use stateid's 3366 assigned by the original server. Therefore the new server must 3367 recognize these stateid's as valid. This holds true for the clientid 3368 as well. Since responsibility for an entire file system is 3369 transferred with a migration event, there is no possibility that 3370 conflicts will arise on the new server as a result of the transfer of 3371 locks. 3373 As part of the transfer of information between servers, leases would 3374 be transferred as well. The leases being transferred to the new 3375 server will typically have a different expiration time from those for 3376 the same client, previously on the new server. To maintain the 3377 property that all leases on a given server for a given client expire 3378 at the same time, the server should advance the expiration time to 3379 the later of the leases being transferred or the leases already 3380 present. This allows the client to maintain lease renewal of both 3381 classes without special effort. 3383 The servers may choose not to transfer the state information upon 3384 migration. However, this choice is discouraged. In this case, when 3385 the client presents state information from the original server, the 3386 client must be prepared to receive either NFS4ERR_STALE_CLIENTID or 3387 NFS4ERR_STALE_STATEID from the new server. The client should then 3388 recover its state information as it normally would in response to a 3389 server failure. The new server must take care to allow for the 3390 recovery of state information as it would in the event of server 3391 restart. 3393 8.13.2. Replication and State 3395 Since client switch-over in the case of replication is not under 3397 Draft Specification NFS version 4 Protocol November 2001 3399 server control, the handling of state is different. In this case, 3400 leases, stateid's and clientid's do not have validity across a 3401 transition from one server to another. The client must re-establish 3402 its locks on the new server. This can be compared to the re- 3403 establishment of locks by means of reclaim-type requests after a 3404 server reboot. The difference is that the server has no provision to 3405 distinguish requests reclaiming locks from those obtaining new locks 3406 or to defer the latter. Thus, a client re-establishing a lock on the 3407 new server (by means of a LOCK or OPEN request), may have the 3408 requests denied due to a conflicting lock. Since replication is 3409 intended for read-only use of filesystems, such denial of locks 3410 should not pose large difficulties in practice. When an attempt to 3411 re-establish a lock on a new server is denied, the client should 3412 treat the situation as if his original lock had been revoked. 3414 8.13.3. Notification of Migrated Lease 3416 In the case of lease renewal, the client may not be submitting 3417 requests for a file system that has been migrated to another server. 3418 This can occur because of the implicit lease renewal mechanism. The 3419 client renews leases for all file systems when submitting a request 3420 to any one file system at the server. 3422 In order for the client to schedule renewal of leases that may have 3423 been relocated to the new server, the client must find out about 3424 lease relocation before those leases expire. To accomplish this, all 3425 operations which implicitly renew leases for a client (i.e. OPEN, 3426 CLOSE, READ, WRITE, RENEW, LOCK, LOCKT, LOCKU), will return the error 3427 NFS4ERR_LEASE_MOVED if responsibility for any of the leases to be 3428 renewed has been transferred to a new server. This condition will 3429 continue until the client receives an NFS4ERR_MOVED error and the 3430 server receives the subsequent GETATTR(fs_locations) for an access to 3431 each file system for which a lease has been moved to a new server. 3433 When a client receives an NFS4ERR_LEASE_MOVED error, it should 3434 perform some operation, such as a RENEW, on each file system 3435 associated with the server in question. When the client receives an 3436 NFS4ERR_MOVED error, the client can follow the normal process to 3437 obtain the new server information (through the fs_locations 3438 attribute) and perform renewal of those leases on the new server. If 3439 the server has not had state transferred to it transparently, it will 3440 receive either NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from 3441 the new server, as described above, and can then recover state 3442 information as it does in the event of server failure. 3444 Draft Specification NFS version 4 Protocol November 2001 3446 9. Client-Side Caching 3448 Client-side caching of data, of file attributes, and of file names is 3449 essential to providing good performance with the NFS protocol. 3450 Providing distributed cache coherence is a difficult problem and 3451 previous versions of the NFS protocol have not attempted it. 3452 Instead, several NFS client implementation techniques have been used 3453 to reduce the problems that a lack of coherence poses for users. 3454 These techniques have not been clearly defined by earlier protocol 3455 specifications and it is often unclear what is valid or invalid 3456 client behavior. 3458 The NFS version 4 protocol uses many techniques similar to those that 3459 have been used in previous protocol versions. The NFS version 4 3460 protocol does not provide distributed cache coherence. However, it 3461 defines a more limited set of caching guarantees to allow locks and 3462 share reservations to be used without destructive interference from 3463 client side caching. 3465 In addition, the NFS version 4 protocol introduces a delegation 3466 mechanism which allows many decisions normally made by the server to 3467 be made locally by clients. This mechanism provides efficient 3468 support of the common cases where sharing is infrequent or where 3469 sharing is read-only. 3471 9.1. Performance Challenges for Client-Side Caching 3473 Caching techniques used in previous versions of the NFS protocol have 3474 been successful in providing good performance. However, several 3475 scalability challenges can arise when those techniques are used with 3476 very large numbers of clients. This is particularly true when 3477 clients are geographically distributed which classically increases 3478 the latency for cache revalidation requests. 3480 The previous versions of the NFS protocol repeat their file data 3481 cache validation requests at the time the file is opened. This 3482 behavior can have serious performance drawbacks. A common case is 3483 one in which a file is only accessed by a single client. Therefore, 3484 sharing is infrequent. 3486 In this case, repeated reference to the server to find that no 3487 conflicts exist is expensive. A better option with regards to 3488 performance is to allow a client that repeatedly opens a file to do 3489 so without reference to the server. This is done until potentially 3490 conflicting operations from another client actually occur. 3492 A similar situation arises in connection with file locking. Sending 3493 file lock and unlock requests to the server as well as the read and 3494 write requests necessary to make data caching consistent with the 3495 locking semantics (see the section "Data Caching and File Locking") 3496 can severely limit performance. When locking is used to provide 3498 Draft Specification NFS version 4 Protocol November 2001 3500 protection against infrequent conflicts, a large penalty is incurred. 3501 This penalty may discourage the use of file locking by applications. 3503 The NFS version 4 protocol provides more aggressive caching 3504 strategies with the following design goals: 3506 o Compatibility with a large range of server semantics. 3508 o Provide the same caching benefits as previous versions of the 3509 NFS protocol when unable to provide the more aggressive model. 3511 o Requirements for aggressive caching are organized so that a 3512 large portion of the benefit can be obtained even when not all 3513 of the requirements can be met. 3515 The appropriate requirements for the server are discussed in later 3516 sections in which specific forms of caching are covered. (see the 3517 section "Open Delegation"). 3519 9.2. Delegation and Callbacks 3521 Recallable delegation of server responsibilities for a file to a 3522 client improves performance by avoiding repeated requests to the 3523 server in the absence of inter-client conflict. With the use of a 3524 "callback" RPC from server to client, a server recalls delegated 3525 responsibilities when another client engages in sharing of a 3526 delegated file. 3528 A delegation is passed from the server to the client, specifying the 3529 object of the delegation and the type of delegation. There are 3530 different types of delegations but each type contains a stateid to be 3531 used to represent the delegation when performing operations that 3532 depend on the delegation. This stateid is similar to those 3533 associated with locks and share reservations but differs in that the 3534 stateid for a delegation is associated with a clientid and may be 3535 used on behalf of all the nfs_lockowners for the given client. A 3536 delegation is made to the client as a whole and not to any specific 3537 process or thread of control within it. 3539 Because callback RPCs may not work in all environments (due to 3540 firewalls, for example), correct protocol operation does not depend 3541 on them. Preliminary testing of callback functionality by means of a 3542 CB_NULL procedure determines whether callbacks can be supported. The 3543 CB_NULL procedure checks the continuity of the callback path. A 3544 server makes a preliminary assessment of callback availability to a 3545 given client and avoids delegating responsibilities until it has 3546 determined that callbacks are supported. Because the granting of a 3547 delegation is always conditional upon the absence of conflicting 3548 access, clients must not assume that a delegation will be granted and 3549 they must always be prepared for OPENs to be processed without any 3551 Draft Specification NFS version 4 Protocol November 2001 3553 delegations being granted. 3555 Once granted, a delegation behaves in most ways like a lock. There 3556 is an associated lease that is subject to renewal together with all 3557 of the other leases held by that client. 3559 Unlike locks, an operation by a second client to a delegated file 3560 will cause the server to recall a delegation through a callback. 3562 On recall, the client holding the delegation must flush modified 3563 state (such as modified data) to the server and return the 3564 delegation. The conflicting request will not receive a response 3565 until the recall is complete. The recall is considered complete when 3566 the client returns the delegation or the server times out on the 3567 recall and revokes the delegation as a result of the timeout. 3568 Following the resolution of the recall, the server has the 3569 information necessary to grant or deny the second client's request. 3571 At the time the client receives a delegation recall, it may have 3572 substantial state that needs to be flushed to the server. Therefore, 3573 the server should allow sufficient time for the delegation to be 3574 returned since it may involve numerous RPCs to the server. If the 3575 server is able to determine that the client is diligently flushing 3576 state to the server as a result of the recall, the server may extend 3577 the usual time allowed for a recall. However, the time allowed for 3578 recall completion should not be unbounded. 3580 An example of this is when responsibility to mediate opens on a given 3581 file is delegated to a client (see the section "Open Delegation"). 3582 The server will not know what opens are in effect on the client. 3583 Without this knowledge the server will be unable to determine if the 3584 access and deny state for the file allows any particular open until 3585 the delegation for the file has been returned. 3587 A client failure or a network partition can result in failure to 3588 respond to a recall callback. In this case, the server will revoke 3589 the delegation which in turn will render useless any modified state 3590 still on the client. 3592 9.2.1. Delegation Recovery 3594 There are three situations that delegation recovery must deal with: 3596 o Client reboot or restart 3598 o Server reboot or restart 3600 o Network partition (full or callback-only) 3602 In the event the client reboots or restarts, the failure to renew 3604 Draft Specification NFS version 4 Protocol November 2001 3606 leases will result in the revocation of record locks and share 3607 reservations. Delegations, however, may be treated a bit 3608 differently. 3610 There will be situations in which delegations will need to be 3611 reestablished after a client reboots or restarts. The reason for 3612 this is the client may have file data stored locally and this data 3613 was associated with the previously held delegations. The client will 3614 need to reestablish the appropriate file state on the server. 3616 To allow for this type of client recovery, the server may extend the 3617 period for delegation recovery beyond the typical lease expiration 3618 period. This implies that requests from other clients that conflict 3619 with these delegations will need to wait. Because the normal recall 3620 process may require significant time for the client to flush changed 3621 state to the server, other clients need be prepared for delays that 3622 occur because of a conflicting delegation. This longer interval 3623 would increase the window for clients to reboot and consult stable 3624 storage so that the delegations can be reclaimed. For open 3625 delegations, such delegations are reclaimed using OPEN with a claim 3626 type of CLAIM_DELEGATE_PREV. (See the sections on "Data Caching and 3627 Revocation" and "Operation 18: OPEN" for discussion of open 3628 delegation and the details of OPEN respectively). 3630 When the server reboots or restarts, delegations are reclaimed (using 3631 the OPEN operation with CLAIM_DELEGATE_PREV) in a similar fashion to 3632 record locks and share reservations. However, there is a slight 3633 semantic difference. In the normal case if the server decides that a 3634 delegation should not be granted, it performs the requested action 3635 (e.g. OPEN) without granting any delegation. For reclaim, the server 3636 grants the delegation but a special designation is applied so that 3637 the client treats the delegation as having been granted but recalled 3638 by the server. Because of this, the client has the duty to write all 3639 modified state to the server and then return the delegation. This 3640 process of handling delegation reclaim reconciles three principles of 3641 the NFS Version 4 protocol: 3643 o Upon reclaim, a client reporting resources assigned to it by an 3644 earlier server instance must be granted those resources. 3646 o The server has unquestionable authority to determine whether 3647 delegations are to be granted and, once granted, whether they 3648 are to be continued. 3650 o The use of callbacks is not to be depended upon until the client 3651 has proven its ability to receive them. 3653 When a network partition occurs, delegations are subject to freeing 3654 by the server when the lease renewal period expires. This is similar 3655 to the behavior for locks and share reservations. For delegations, 3656 however, the server may extend the period in which conflicting 3658 Draft Specification NFS version 4 Protocol November 2001 3660 requests are held off. Eventually the occurrence of a conflicting 3661 request from another client will cause revocation of the delegation. 3662 A loss of the callback path (e.g. by later network configuration 3663 change) will have the same effect. A recall request will fail and 3664 revocation of the delegation will result. 3666 A client normally finds out about revocation of a delegation when it 3667 uses a stateid associated with a delegation and receives the error 3668 NFS4ERR_EXPIRED. It also may find out about delegation revocation 3669 after a client reboot when it attempts to reclaim a delegation and 3670 receives that same error. Note that in the case of a revoked write 3671 open delegation, there are issues because data may have been modified 3672 by the client whose delegation is revoked and separately by other 3673 clients. See the section "Revocation Recovery for Write Open 3674 Delegation" for a discussion of such issues. Note also that when 3675 delegations are revoked, information about the revoked delegation 3676 will be written by the server to stable storage (as described in the 3677 section "Crash Recovery"). This is done to deal with the case in 3678 which a server reboots after revoking a delegation but before the 3679 client holding the revoked delegation is notified about the 3680 revocation. 3682 9.3. Data Caching 3684 When applications share access to a set of files, they need to be 3685 implemented so as to take account of the possibility of conflicting 3686 access by another application. This is true whether the applications 3687 in question execute on different clients or reside on the same 3688 client. 3690 Share reservations and record locks are the facilities the NFS 3691 version 4 protocol provides to allow applications to coordinate 3692 access by providing mutual exclusion facilities. The NFS version 4 3693 protocol's data caching must be implemented such that it does not 3694 invalidate the assumptions that those using these facilities depend 3695 upon. 3697 9.3.1. Data Caching and OPENs 3699 In order to avoid invalidating the sharing assumptions that 3700 applications rely on, NFS version 4 clients should not provide cached 3701 data to applications or modify it on behalf of an application when it 3702 would not be valid to obtain or modify that same data via a READ or 3703 WRITE operation. 3705 Furthermore, in the absence of open delegation (see the section "Open 3706 Delegation") two additional rules apply. Note that these rules are 3707 obeyed in practice by many NFS version 2 and version 3 clients. 3709 o First, cached data present on a client must be revalidated after 3711 Draft Specification NFS version 4 Protocol November 2001 3713 doing an OPEN. This is to ensure that the data for the OPENed 3714 file is still correctly reflected in the client's cache. This 3715 validation must be done at least when the client's OPEN 3716 operation includes DENY=WRITE or BOTH thus terminating a period 3717 in which other clients may have had the opportunity to open the 3718 file with WRITE access. Clients may choose to do the 3719 revalidation more often (i.e. at OPENs specifying DENY=NONE) to 3720 parallel the NFS version 3 protocol's practice for the benefit 3721 of users assuming this degree of cache revalidation. 3723 o Second, modified data must be flushed to the server before 3724 closing a file OPENed for write. This is complementary to the 3725 first rule. If the data is not flushed at CLOSE, the 3726 revalidation done after client OPENs as file is unable to 3727 achieve its purpose. The other aspect to flushing the data 3728 before close is that the data must be committed to stable 3729 storage, at the server, before the CLOSE operation is requested 3730 by the client. In the case of a server reboot or restart and a 3731 CLOSEd file, it may not be possible to retransmit the data to be 3732 written to the file. Hence, this requirement. 3734 9.3.2. Data Caching and File Locking 3736 For those applications that choose to use file locking instead of 3737 share reservations to exclude inconsistent file access, there is an 3738 analogous set of constraints that apply to client side data caching. 3739 These rules are effective only if the file locking is used in a way 3740 that matches in an equivalent way the actual READ and WRITE 3741 operations executed. This is as opposed to file locking that is 3742 based on pure convention. For example, it is possible to manipulate 3743 a two-megabyte file by dividing the file into two one-megabyte 3744 regions and protecting access to the two regions by file locks on 3745 bytes zero and one. A lock for write on byte zero of the file would 3746 represent the right to do READ and WRITE operations on the first 3747 region. A lock for write on byte one of the file would represent the 3748 right to do READ and WRITE operations on the second region. As long 3749 as all applications manipulating the file obey this convention, they 3750 will work on a local file system. However, they may not work with 3751 the NFS version 4 protocol unless clients refrain from data caching. 3753 The rules for data caching in the file locking environment are: 3755 o First, when a client obtains a file lock for a particular 3756 region, the data cache corresponding to that region (if any 3757 cache data exists) must be revalidated. If the change attribute 3758 indicates that the file may have been updated since the cached 3759 data was obtained, the client must flush or invalidate the 3760 cached data for the newly locked region. A client might choose 3761 to invalidate all of non-modified cached data that it has for 3762 the file but the only requirement for correct operation is to 3763 invalidate all of the data in the newly locked region. 3765 Draft Specification NFS version 4 Protocol November 2001 3767 o Second, before releasing a write lock for a region, all modified 3768 data for that region must be flushed to the server. The 3769 modified data must also be written to stable storage. 3771 Note that flushing data to the server and the invalidation of cached 3772 data must reflect the actual byte ranges locked or unlocked. 3773 Rounding these up or down to reflect client cache block boundaries 3774 will cause problems if not carefully done. For example, writing a 3775 modified block when only half of that block is within an area being 3776 unlocked may cause invalid modification to the region outside the 3777 unlocked area. This, in turn, may be part of a region locked by 3778 another client. Clients can avoid this situation by synchronously 3779 performing portions of write operations that overlap that portion 3780 (initial or final) that is not a full block. Similarly, invalidating 3781 a locked area which is not an integral number of full buffer blocks 3782 would require the client to read one or two partial blocks from the 3783 server if the revalidation procedure shows that the data which the 3784 client possesses may not be valid. 3786 The data that is written to the server as a pre-requisite to the 3787 unlocking of a region must be written, at the server, to stable 3788 storage. The client may accomplish this either with synchronous 3789 writes or by following asynchronous writes with a COMMIT operation. 3790 This is required because retransmission of the modified data after a 3791 server reboot might conflict with a lock held by another client. 3793 A client implementation may choose to accommodate applications which 3794 use record locking in non-standard ways (e.g. using a record lock as 3795 a global semaphore) by flushing to the server more data upon an LOCKU 3796 than is covered by the locked range. This may include modified data 3797 within files other than the one for which the unlocks are being done. 3798 In such cases, the client must not interfere with applications whose 3799 READs and WRITEs are being done only within the bounds of record 3800 locks which the application holds. For example, an application locks 3801 a single byte of a file and proceeds to write that single byte. A 3802 client that chose to handle a LOCKU by flushing all modified data to 3803 the server could validly write that single byte in response to an 3804 unrelated unlock. However, it would not be valid to write the entire 3805 block in which that single written byte was located since it includes 3806 an area that is not locked and might be locked by another client. 3807 Client implementations can avoid this problem by dividing files with 3808 modified data into those for which all modifications are done to 3809 areas covered by an appropriate record lock and those for which there 3810 are modifications not covered by a record lock. Any writes done for 3811 the former class of files must not include areas not locked and thus 3812 not modified on the client. 3814 9.3.3. Data Caching and Mandatory File Locking 3816 Client side data caching needs to respect mandatory file locking when 3817 it is in effect. The presence of mandatory file locking for a given 3819 Draft Specification NFS version 4 Protocol November 2001 3821 file is indicated in the result flags for an OPEN. When mandatory 3822 locking is in effect for a file, the client must check for an 3823 appropriate file lock for data being read or written. If a lock 3824 exists for the range being read or written, the client may satisfy 3825 the request using the client's validated cache. If an appropriate 3826 file lock is not held for the range of the read or write, the read or 3827 write request must not be satisfied by the client's cache and the 3828 request must be sent to the server for processing. When a read or 3829 write request partially overlaps a locked region, the request should 3830 be subdivided into multiple pieces with each region (locked or not) 3831 treated appropriately. 3833 9.3.4. Data Caching and File Identity 3835 When clients cache data, the file data needs to organized according 3836 to the file system object to which the data belongs. For NFS version 3837 3 clients, the typical practice has been to assume for the purpose of 3838 caching that distinct filehandles represent distinct file system 3839 objects. The client then has the choice to organize and maintain the 3840 data cache on this basis. 3842 In the NFS version 4 protocol, there is now the possibility to have 3843 significant deviations from a "one filehandle per object" model 3844 because a filehandle may be constructed on the basis of the object's 3845 pathname. Therefore, clients need a reliable method to determine if 3846 two filehandles designate the same file system object. If clients 3847 were simply to assume that all distinct filehandles denote distinct 3848 objects and proceed to do data caching on this basis, caching 3849 inconsistencies would arise between the distinct client side objects 3850 which mapped to the same server side object. 3852 By providing a method to differentiate filehandles, the NFS version 4 3853 protocol alleviates a potential functional regression in comparison 3854 with the NFS version 3 protocol. Without this method, caching 3855 inconsistencies within the same client could occur and this has not 3856 been present in previous versions of the NFS protocol. Note that it 3857 is possible to have such inconsistencies with applications executing 3858 on multiple clients but that is not the issue being addressed here. 3860 For the purposes of data caching, the following steps allow an NFS 3861 version 4 client to determine whether two distinct filehandles denote 3862 the same server side object: 3864 o If GETATTR directed to two filehandles have different values of 3865 the fsid attribute, then the filehandles represent distinct 3866 objects. 3868 o If GETATTR for any file with an fsid that matches the fsid of 3869 the two filehandles in question returns a unique_handles 3870 attribute with a value of TRUE, then the two objects are 3872 Draft Specification NFS version 4 Protocol November 2001 3874 distinct. 3876 o If GETATTR directed to the two filehandles does not return the 3877 fileid attribute for one or both of the handles, then the it 3878 cannot be determined whether the two objects are the same. 3879 Therefore, operations which depend on that knowledge (e.g. 3880 client side data caching) cannot be done reliably. 3882 o If GETATTR directed to the two filehandles returns different 3883 values for the fileid attribute, then they are distinct objects. 3885 o Otherwise they are the same object. 3887 9.4. Open Delegation 3889 When a file is being OPENed, the server may delegate further handling 3890 of opens and closes for that file to the opening client. Any such 3891 delegation is recallable, since the circumstances that allowed for 3892 the delegation are subject to change. In particular, the server may 3893 receive a conflicting OPEN from another client, the server must 3894 recall the delegation before deciding whether the OPEN from the other 3895 client may be granted. Making a delegation is up to the server and 3896 clients should not assume that any particular OPEN either will or 3897 will not result in an open delegation. The following is a typical 3898 set of conditions that servers might use in deciding whether OPEN 3899 should be delegated: 3901 o The client must be able to respond to the server's callback 3902 requests. The server will use the CB_NULL procedure for a test 3903 of callback ability. 3905 o The client must have responded properly to previous recalls. 3907 o There must be no current open conflicting with the requested 3908 delegation. 3910 o There should be no current delegation that conflicts with the 3911 delegation being requested. 3913 o The probability of future conflicting open requests should be 3914 low based on the recent history of the file. 3916 o The existence of any server-specific semantics of OPEN/CLOSE 3917 that would make the required handling incompatible with the 3918 prescribed handling that the delegated client would apply (see 3919 below). 3921 There are two types of open delegations, read and write. A read open 3922 delegation allows a client to handle, on its own, requests to open a 3923 file for reading that do not deny read access to others. Multiple 3924 read open delegations may be outstanding simultaneously and do not 3926 Draft Specification NFS version 4 Protocol November 2001 3928 conflict. A write open delegation allows the client to handle, on 3929 its own, all opens. Only one write open delegation may exist for a 3930 given file at a given time and it is inconsistent with any read open 3931 delegations. 3933 When a client has a read open delegation, it may not make any changes 3934 to the contents or attributes of the file but it is assured that no 3935 other client may do so. When a client has a write open delegation, 3936 it may modify the file data since no other client will be accessing 3937 the file's data. The client holding a write delegation may only 3938 affect file attributes which are intimately connected with the file 3939 data: object_size, time_modify, change. 3941 When a client has an open delegation, it does not send OPENs or 3942 CLOSEs to the server but updates the appropriate status internally. 3943 For a read open delegation, opens that cannot be handled locally 3944 (opens for write or that deny read access) must be sent to the 3945 server. 3947 When an open delegation is made, the response to the OPEN contains an 3948 open delegation structure which specifies the following: 3950 o the type of delegation (read or write) 3952 o space limitation information to control flushing of data on 3953 close (write open delegation only, see the section "Open 3954 Delegation and Data Caching") 3956 o an nfsace4 specifying read and write permissions 3958 o a stateid to represent the delegation for READ and WRITE 3960 The stateid is separate and distinct from the stateid for the OPEN 3961 proper. The standard stateid, unlike the delegation stateid, is 3962 associated with a particular nfs_lockowner and will continue to be 3963 valid after the delegation is recalled and the file remains open. 3965 When a request internal to the client is made to open a file and open 3966 delegation is in effect, it will be accepted or rejected solely on 3967 the basis of the following conditions. Any requirement for other 3968 checks to be made by the delegate should result in open delegation 3969 being denied so that the checks can be made by the server itself. 3971 o The access and deny bits for the request and the file as 3972 described in the section "Share Reservations". 3974 o The read and write permissions as determined below. 3976 The nfsace4 passed with delegation can be used to avoid frequent 3977 ACCESS calls. The permission check should be as follows: 3979 Draft Specification NFS version 4 Protocol November 2001 3981 o If the nfsace4 indicates that the open may be done, then it 3982 should be granted without reference to the server. 3984 o If the nfsace4 indicates that the open may not be done, then an 3985 ACCESS request must be sent to the server to obtain the 3986 definitive answer. 3988 The server may return an nfsace4 that is more restrictive than the 3989 actual ACL of the file. This includes an nfsace4 that specifies 3990 denial of all access. Note that some common practices such as 3991 mapping the traditional user "root" to the user "nobody" may make it 3992 incorrect to return the actual ACL of the file in the delegation 3993 response. 3995 The use of delegation together with various other forms of caching 3996 creates the possibility that no server authentication will ever be 3997 performed for a given user since all of the user's requests might be 3998 satisfied locally. Where the client is depending on the server for 3999 authentication, the client should be sure authentication occurs for 4000 each user by use of the ACCESS operation. This should be the case 4001 even if an ACCESS operation would not be required otherwise. As 4002 mentioned before, the server may enforce frequent authentication by 4003 returning an nfsace4 denying all access with every open delegation. 4005 9.4.1. Open Delegation and Data Caching 4007 OPEN delegation allows much of the message overhead associated with 4008 the opening and closing files to be eliminated. An open when an open 4009 delegation is in effect does not require that a validation message be 4010 sent to the server. The continued endurance of the "read open 4011 delegation" provides a guarantee that no OPEN for write and thus no 4012 write has occurred. Similarly, when closing a file opened for write 4013 and if write open delegation is in effect, the data written does not 4014 have to be flushed to the server until the open delegation is 4015 recalled. The continued endurance of the open delegation provides a 4016 guarantee that no open and thus no read or write has been done by 4017 another client. 4019 For the purposes of open delegation, READs and WRITEs done without an 4020 OPEN are treated as the functional equivalents of a corresponding 4021 type of OPEN. This refers to the READs and WRITEs that use the 4022 special stateids consisting of all zero bits or all one bits. 4023 Therefore, READs or WRITEs with a special stateid done by another 4024 client will force the server to recall a write open delegation. A 4025 WRITE with a special stateid done by another client will force a 4026 recall of read open delegations. 4028 With delegations, a client is able to avoid writing data to the 4029 server when the CLOSE of a file is serviced. The CLOSE operation is 4030 the usual point at which the client is notified of a lack of stable 4031 storage for the modified file data generated by the application. At 4033 Draft Specification NFS version 4 Protocol November 2001 4035 the CLOSE, file data is written to the server and through normal 4036 accounting the server is able to determine if the available file 4037 system space for the data has been exceeded (i.e. server returns 4038 NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. 4039 The introduction of delegations requires that a alternative method be 4040 in place for the same type of communication to occur between client 4041 and server. 4043 In the delegation response, the server provides either the limit of 4044 the size of the file or the number of modified blocks and associated 4045 block size. The server must ensure that the client will be able to 4046 flush data to the server of a size equal to that provided in the 4047 original delegation. The server must make this assurance for all 4048 outstanding delegations. Therefore, the server must be careful in 4049 its management of available space for new or modified data taking 4050 into account available file system space and any applicable quotas. 4051 The server can recall delegations as a result of managing the 4052 available file system space. The client should abide by the server's 4053 state space limits for delegations. If the client exceeds the stated 4054 limits for the delegation, the server's behavior is undefined. 4056 Based on server conditions, quotas or available file system space, 4057 the server may grant write open delegations with very restrictive 4058 space limitations. The limitations may be defined in a way that will 4059 always force modified data to be flushed to the server on close. 4061 With respect to authentication, flushing modified data to the server 4062 after a CLOSE has occurred may be problematic. For example, the user 4063 of the application may have logged off of the client and unexpired 4064 authentication credentials may not be present. In this case, the 4065 client may need to take special care to ensure that local unexpired 4066 credentials will in fact be available. This may be accomplished by 4067 tracking the expiration time of credentials and flushing data well in 4068 advance of their expiration or by making private copies of 4069 credentials to assure their availability when needed. 4071 9.4.2. Open Delegation and File Locks 4073 When a client holds a write open delegation, lock operations are 4074 performed locally. This includes those required for mandatory file 4075 locking. This can be done since the delegation implies that there 4076 can be no conflicting locks. Similarly, all of the revalidations 4077 that would normally be associated with obtaining locks and the 4078 flushing of data associated with the releasing of locks need not be 4079 done. 4081 9.4.3. Recall of Open Delegation 4083 The following events necessitate recall of an open delegation: 4085 Draft Specification NFS version 4 Protocol November 2001 4087 o Potentially conflicting OPEN request (or READ/WRITE done with 4088 "special" stateid) 4090 o SETATTR issued by another client 4092 o REMOVE request for the file 4094 o RENAME request for the file as either source or target of the 4095 RENAME 4097 Whether a RENAME of a directory in the path leading to the file 4098 results in recall of an open delegation depends on the semantics of 4099 the server file system. If that file system denies such RENAMEs when 4100 a file is open, the recall must be performed to determine whether the 4101 file in question is, in fact, open. 4103 In addition to the situations above, the server may choose to recall 4104 open delegations at any time if resource constraints make it 4105 advisable to do so. Clients should always be prepared for the 4106 possibility of recall. 4108 The server needs to employ special handling for a GETATTR where the 4109 target is a file that has a write open delegation in effect. In this 4110 case, the client holding the delegation needs to be interrogated. 4111 The server will use a CB_GETATTR callback, if the GETATTR attribute 4112 bits include any of the attributes that a write open delegate may 4113 modify (object_size, time_modify, change). 4115 When a client receives a recall for an open delegation, it needs to 4116 update state on the server before returning the delegation. These 4117 same updates must be done whenever a client chooses to return a 4118 delegation voluntarily. The following items of state need to be 4119 dealt with: 4121 o If the file associated with the delegation is no longer open and 4122 no previous CLOSE operation has been sent to the server, a CLOSE 4123 operation must be sent to the server. 4125 o If a file has other open references at the client, then OPEN 4126 operations must be sent to the server. The appropriate stateids 4127 will be provided by the server for subsequent use by the client 4128 since the delegation stateid will not longer be valid. These 4129 OPEN requests are done with the claim type of 4130 CLAIM_DELEGATE_CUR. This will allow the presentation of the 4131 delegation stateid so that the client can establish the 4132 appropriate rights to perform the OPEN. (see the section 4133 "Operation 18: OPEN" for details.) 4135 o If there are granted file locks, the corresponding LOCK 4136 operations need to be performed. This applies to the write open 4137 delegation case only. 4139 Draft Specification NFS version 4 Protocol November 2001 4141 o For a write open delegation, if at the time of recall the file 4142 is not open for write, all modified data for the file must be 4143 flushed to the server. If the delegation had not existed, the 4144 client would have done this data flush before the CLOSE 4145 operation. 4147 o For a write open delegation when a file is still open at the 4148 time of recall, any modified data for the file needs to be 4149 flushed to the server. 4151 o With the write open delegation in place, it is possible that the 4152 file was truncated during the duration of the delegation. For 4153 example, the truncation could have occurred as a result of an 4154 OPEN UNCHECKED with a object_size attribute value of zero. 4155 Therefore, if a truncation of the file has occurred and this 4156 operation has not been propagated to the server, the truncation 4157 must occur before any modified data is written to the server. 4159 In the case of write open delegation, file locking imposes some 4160 additional requirements. The flushing of any modified data in any 4161 region for which a write lock was released while the write open 4162 delegation was in effect is what is required to precisely maintain 4163 the associated invariant. However, because the write open delegation 4164 implies no other locking by other clients, a simpler implementation 4165 is to flush all modified data for the file (as described just above) 4166 if any write lock has been released while the write open delegation 4167 was in effect. 4169 9.4.4. Delegation Revocation 4171 At the point a delegation is revoked, if there are associated opens 4172 on the client, the applications holding these opens need to be 4173 notified. This notification usually occurs by returning errors for 4174 READ/WRITE operations or when a close is attempted for the open file. 4176 If no opens exist for the file at the point the delegation is 4177 revoked, then notification of the revocation is unnecessary. 4178 However, if there is modified data present at the client for the 4179 file, the user of the application should be notified. Unfortunately, 4180 it may not be possible to notify the user since active applications 4181 may not be present at the client. See the section "Revocation 4182 Recovery for Write Open Delegation" for additional details. 4184 9.5. Data Caching and Revocation 4186 When locks and delegations are revoked, the assumptions upon which 4187 successful caching depend are no longer guaranteed. The owner of the 4188 locks or share reservations which have been revoked needs to be 4189 notified. This notification includes applications with a file open 4190 that has a corresponding delegation which has been revoked. Cached 4192 Draft Specification NFS version 4 Protocol November 2001 4194 data associated with the revocation must be removed from the client. 4195 In the case of modified data existing in the client's cache, that 4196 data must be removed from the client without it being written to the 4197 server. As mentioned, the assumptions made by the client are no 4198 longer valid at the point when a lock or delegation has been revoked. 4199 For example, another client may have been granted a conflicting lock 4200 after the revocation of the lock at the first client. Therefore, the 4201 data within the lock range may have been modified by the other 4202 client. Obviously, the first client is unable to guarantee to the 4203 application what has occurred to the file in the case of revocation. 4205 Notification to a lock owner will in many cases consist of simply 4206 returning an error on the next and all subsequent READs/WRITEs to the 4207 open file or on the close. Where the methods available to a client 4208 make such notification impossible because errors for certain 4209 operations may not be returned, more drastic action such as signals 4210 or process termination may be appropriate. The justification for 4211 this is that an invariant for which an application depends on may be 4212 violated. Depending on how errors are typically treated for the 4213 client operating environment, further levels of notification 4214 including logging, console messages, and GUI pop-ups may be 4215 appropriate. 4217 9.5.1. Revocation Recovery for Write Open Delegation 4219 Revocation recovery for a write open delegation poses the special 4220 issue of modified data in the client cache while the file is not 4221 open. In this situation, any client which does not flush modified 4222 data to the server on each close must ensure that the user receives 4223 appropriate notification of the failure as a result of the 4224 revocation. Since such situations may require human action to 4225 correct problems, notification schemes in which the appropriate user 4226 or administrator is notified may be necessary. Logging and console 4227 messages are typical examples. 4229 If there is modified data on the client, it must not be flushed 4230 normally to the server. A client may attempt to provide a copy of 4231 the file data as modified during the delegation under a different 4232 name in the file system name space to ease recovery. Unless the 4233 client can determine that the file has not modified by any other 4234 client, this technique must be limited to situations in which a 4235 client has a complete cached copy of the file in question. Use of 4236 such a technique may be limited to files under a certain size or may 4237 only be used when sufficient disk space is guaranteed to be available 4238 within the target file system and when the client has sufficient 4239 buffering resources to keep the cached copy available until it is 4240 properly stored to the target file system. 4242 Draft Specification NFS version 4 Protocol November 2001 4244 9.6. Attribute Caching 4246 The attributes discussed in this section do not include named 4247 attributes. Individual named attributes are analogous to files and 4248 caching of the data for these needs to be handled just as data 4249 caching is for ordinary files. Similarly, LOOKUP results from an 4250 OPENATTR directory are to be cached on the same basis as any other 4251 pathnames and similarly for directory contents. 4253 Clients may cache file attributes obtained from the server and use 4254 them to avoid subsequent GETATTR requests. Such caching is write 4255 through in that modification to file attributes is always done by 4256 means of requests to the server and should not be done locally and 4257 cached. The exception to this are modifications to attributes that 4258 are intimately connected with data caching. Therefore, extending a 4259 file by writing data to the local data cache is reflected immediately 4260 in the object_size as seen on the client without this change being 4261 immediately reflected on the server. Normally such changes are not 4262 propagated directly to the server but when the modified data is 4263 flushed to the server, analogous attribute changes are made on the 4264 server. When open delegation is in effect, the modified attributes 4265 may be returned to the server in the response to a CB_RECALL call. 4267 The result of local caching of attributes is that the attribute 4268 caches maintained on individual clients will not be coherent. Changes 4269 made in one order on the server may be seen in a different order on 4270 one client and in a third order on a different client. 4272 The typical file system application programming interfaces do not 4273 provide means to atomically modify or interrogate attributes for 4274 multiple files at the same time. The following rules provide an 4275 environment where the potential incoherences mentioned above can be 4276 reasonably managed. These rules are derived from the practice of 4277 previous NFS protocols. 4279 o All attributes for a given file (per-fsid attributes excepted) 4280 are cached as a unit at the client so that no non- 4281 serializability can arise within the context of a single file. 4283 o An upper time boundary is maintained on how long a client cache 4284 entry can be kept without being refreshed from the server. 4286 o When operations are performed that change attributes at the 4287 server, the updated attribute set is requested as part of the 4288 containing RPC. This includes directory operations that update 4289 attributes indirectly. This is accomplished by following the 4290 modifying operation with a GETATTR operation and then using the 4291 results of the GETATTR to update the client's cached attributes. 4293 Note that if the full set of attributes to be cached is requested by 4294 READDIR, the results can be cached by the client on the same basis as 4295 attributes obtained via GETATTR. 4297 Draft Specification NFS version 4 Protocol November 2001 4299 A client may validate its cached version of attributes for a file by 4300 fetching only the change attribute and assuming that if the change 4301 attribute has the same value as it did when the attributes were 4302 cached, then no attributes have changed. The possible exception is 4303 the attribute time_access. 4305 9.7. Name Caching 4307 The results of LOOKUP and READDIR operations may be cached to avoid 4308 the cost of subsequent LOOKUP operations. Just as in the case of 4309 attribute caching, inconsistencies may arise among the various client 4310 caches. To mitigate the effects of these inconsistencies and given 4311 the context of typical file system APIs, the following rules should 4312 be followed: 4314 o The results of unsuccessful LOOKUPs should not be cached, unless 4315 they are specifically reverified at the point of use. 4317 o An upper time boundary is maintained on how long a client name 4318 cache entry can be kept without verifying that the entry has not 4319 been made invalid by a directory change operation performed by 4320 another client. 4322 When a client is not making changes to a directory for which there 4323 exist name cache entries, the client needs to periodically fetch 4324 attributes for that directory to ensure that it is not being 4325 modified. After determining that no modification has occurred, the 4326 expiration time for the associated name cache entries may be updated 4327 to be the current time plus the name cache staleness bound. 4329 When a client is making changes to a given directory, it needs to 4330 determine whether there have been changes made to the directory by 4331 other clients. It does this by using the change attribute as 4332 reported before and after the directory operation in the associated 4333 change_info4 value returned for the operation. The server is able to 4334 communicate to the client whether the change_info4 data is provided 4335 atomically with respect to the directory operation. If the change 4336 values are provided atomically, the client is then able to compare 4337 the pre-operation change value with the change value in the client's 4338 name cache. If the comparison indicates that the directory was 4339 updated by another client, the name cache associated with the 4340 modified directory is purged from the client. If the comparison 4341 indicates no modification, the name cache can be updated on the 4342 client to reflect the directory operation and the associated timeout 4343 extended. The post-operation change value needs to be saved as the 4344 basis for future change_info4 comparisons. 4346 As demonstrated by the scenario above, name caching requires that the 4347 client revalidate name cache data by inspecting the change attribute 4348 of a directory at the point when the name cache item was cached. 4349 This requires that the server update the change attribute for 4351 Draft Specification NFS version 4 Protocol November 2001 4353 directories when the contents of the corresponding directory is 4354 modified. For a client to use the change_info4 information 4355 appropriately and correctly, the server must report the pre and post 4356 operation change attribute values atomically. When the server is 4357 unable to report the before and after values atomically with respect 4358 to the directory operation, the server must indicate that fact in the 4359 change_info4 return value. When the information is not atomically 4360 reported, the client should not assume that other clients have not 4361 changed the directory. 4363 9.8. Directory Caching 4365 The results of READDIR operations may be used to avoid subsequent 4366 READDIR operations. Just as in the cases of attribute and name 4367 caching, inconsistencies may arise among the various client caches. 4368 To mitigate the effects of these inconsistencies, and given the 4369 context of typical file system APIs, the following rules should be 4370 followed: 4372 o Cached READDIR information for a directory which is not obtained 4373 in a single READDIR operation must always be a consistent 4374 snapshot of directory contents. This is determined by using a 4375 GETATTR before the first READDIR and after the last of READDIR 4376 that contributes to the cache. 4378 o An upper time boundary is maintained to indicate the length of 4379 time a directory cache entry is considered valid before the 4380 client must revalidate the cached information. 4382 The revalidation technique parallels that discussed in the case of 4383 name caching. When the client is not changing the directory in 4384 question, checking the change attribute of the directory with GETATTR 4385 is adequate. The lifetime of the cache entry can be extended at 4386 these checkpoints. When a client is modifying the directory, the 4387 client needs to use the change_info4 data to determine whether there 4388 are other clients modifying the directory. If it is determined that 4389 no other client modifications are occurring, the client may update 4390 its directory cache to reflect its own changes. 4392 As demonstrated previously, directory caching requires that the 4393 client revalidate directory cache data by inspecting the change 4394 attribute of a directory at the point when the directory was cached. 4395 This requires that the server update the change attribute for 4396 directories when the contents of the corresponding directory is 4397 modified. For a client to use the change_info4 information 4398 appropriately and correctly, the server must report the pre and post 4399 operation change attribute values atomically. When the server is 4400 unable to report the before and after values atomically with respect 4401 to the directory operation, the server must indicate that fact in the 4402 change_info4 return value. When the information is not atomically 4403 reported, the client should not assume that other clients have not 4405 Draft Specification NFS version 4 Protocol November 2001 4407 changed the directory. 4409 Draft Specification NFS version 4 Protocol November 2001 4411 10. Minor Versioning 4413 To address the requirement of an NFS protocol that can evolve as the 4414 need arises, the NFS version 4 protocol contains the rules and 4415 framework to allow for future minor changes or versioning. 4417 The base assumption with respect to minor versioning is that any 4418 future accepted minor version must follow the IETF process and be 4419 documented in a standards track RFC. Therefore, each minor version 4420 number will correspond to an RFC. Minor version zero of the NFS 4421 version 4 protocol is represented by this RFC. The COMPOUND 4422 procedure will support the encoding of the minor version being 4423 requested by the client. 4425 The following items represent the basic rules for the development of 4426 minor versions. Note that a future minor version may decide to 4427 modify or add to the following rules as part of the minor version 4428 definition. 4430 1 Procedures are not added or deleted 4432 To maintain the general RPC model, NFS version 4 minor versions 4433 will not add or delete procedures from the NFS program. 4435 2 Minor versions may add operations to the COMPOUND and 4436 CB_COMPOUND procedures. 4438 The addition of operations to the COMPOUND and CB_COMPOUND 4439 procedures does not affect the RPC model. 4441 2.1 Minor versions may append attributes to GETATTR4args, bitmap4, 4442 and GETATTR4res. 4444 This allows for the expansion of the attribute model to allow 4445 for future growth or adaptation. 4447 2.2 Minor version X must append any new attributes after the last 4448 documented attribute. 4450 Since attribute results are specified as an opaque array of 4451 per-attribute XDR encoded results, the complexity of adding new 4452 attributes in the midst of the current definitions will be too 4453 burdensome. 4455 3 Minor versions must not modify the structure of an existing 4456 operation's arguments or results. 4458 Draft Specification NFS version 4 Protocol November 2001 4460 Again the complexity of handling multiple structure definitions 4461 for a single operation is too burdensome. New operations should 4462 be added instead of modifying existing structures for a minor 4463 version. 4465 This rule does not preclude the following adaptations in a minor 4466 version. 4468 o adding bits to flag fields such as new attributes to 4469 GETATTR's bitmap4 data type 4471 o adding bits to existing attributes like ACLs that have flag 4472 words 4474 o extending enumerated types (including NFS4ERR_*) with new 4475 values 4477 4 Minor versions may not modify the structure of existing 4478 attributes. 4480 5 Minor versions may not delete operations. 4482 This prevents the potential reuse of a particular operation 4483 "slot" in a future minor version. 4485 6 Minor versions may not delete attributes. 4487 7 Minor versions may not delete flag bits or enumeration values. 4489 8 Minor versions may declare an operation as mandatory to NOT 4490 implement. 4492 Specifying an operation as "mandatory to not implement" is 4493 equivalent to obsoleting an operation. For the client, it means 4494 that the operation should not be sent to the server. For the 4495 server, an NFS error can be returned as opposed to "dropping" 4496 the request as an XDR decode error. This approach allows for 4497 the obsolescence of an operation while maintaining its structure 4498 so that a future minor version can reintroduce the operation. 4500 8.1 Minor versions may declare attributes mandatory to NOT 4501 implement. 4503 8.2 Minor versions may declare flag bits or enumeration values as 4504 mandatory to NOT implement. 4506 Draft Specification NFS version 4 Protocol November 2001 4508 9 Minor versions may downgrade features from mandatory to 4509 recommended, or recommended to optional. 4511 10 Minor versions may upgrade features from optional to recommended 4512 or recommended to mandatory. 4514 11 A client and server that support minor version X must support 4515 minor versions 0 (zero) through X-1 as well. 4517 12 No new features may be introduced as mandatory in a minor 4518 version. 4520 This rule allows for the introduction of new functionality and 4521 forces the use of implementation experience before designating a 4522 feature as mandatory. 4524 13 A client MUST NOT attempt to use a stateid, file handle, or 4525 similar returned object from the COMPOUND procedure with minor 4526 version X for another COMPOUND procedure with minor version Y, 4527 where X != Y. 4529 Draft Specification NFS version 4 Protocol November 2001 4531 11. Internationalization 4533 The primary issue in which NFS needs to deal with 4534 internationalization, or I18N, is with respect to file names and 4535 other strings as used within the protocol. The choice of string 4536 representation must allow reasonable name/string access to clients 4537 which use various languages. The UTF-8 encoding of the UCS as 4538 defined by [ISO10646] allows for this type of access and follows the 4539 policy described in "IETF Policy on Character Sets and Languages", 4540 [RFC2277]. This choice is explained further in the following. 4542 11.1. Universal Versus Local Character Sets 4544 [RFC1345] describes a table of 16 bit characters for many different 4545 languages (the bit encodings match Unicode, though of course RFC1345 4546 is somewhat out of date with respect to current Unicode assignments). 4547 Each character from each language has a unique 16 bit value in the 16 4548 bit character set. Thus this table can be thought of as a universal 4549 character set. [RFC1345] then talks about groupings of subsets of 4550 the entire 16 bit character set into "Charset Tables". For example 4551 one might take all the Greek characters from the 16 bit table (which 4552 are consecutively allocated), and normalize their offsets to a table 4553 that fits in 7 bits. Thus it is determined that "lower case alpha" 4554 is in the same position as "upper case a" in the US-ASCII table, and 4555 "upper case alpha" is in the same position as "lower case a" in the 4556 US-ASCII table. 4558 These normalized subset character sets can be thought of as "local 4559 character sets", suitable for an operating system locale. 4561 Local character sets are not suitable for the NFS protocol. Consider 4562 someone who creates a file with a name in a Swedish character set. 4563 If someone else later goes to access the file with their locale set 4564 to the Swedish language, then there are no problems. But if someone 4565 in say the US-ASCII locale goes to access the file, the file name 4566 will look very different, because the Swedish characters in the 7 bit 4567 table will now be represented in US-ASCII characters on the display. 4568 It would be preferable to give the US-ASCII user a way to display the 4569 file name using Swedish glyphs. In order to do that, the NFS protocol 4570 would have to include the locale with the file name on each operation 4571 to create a file. 4573 But then what of the situation when there is a path name on the 4574 server like: 4576 /component-1/component-2/component-3 4578 Each component could have been created with a different locale. If 4579 one issues CREATE with multi-component path name, and if some of the 4580 leading components already exist, what is to be done with the 4581 existing components? Is the current locale attribute replaced with 4582 the user's current one? These types of situations quickly become too 4584 Draft Specification NFS version 4 Protocol November 2001 4586 complex when there is an alternate solution. 4588 If the NFS version 4 protocol used a universal 16 bit or 32 bit 4589 character set (or an encoding of a 16 bit or 32 bit character set 4590 into octets), then the server and client need not care if the locale 4591 of the user accessing the file is different than the locale of the 4592 user who created the file. The unique 16 bit or 32 bit encoding of 4593 the character allows for determination of what language the character 4594 is from and also how to display that character on the client. The 4595 server need not know what locales are used. 4597 11.2. Overview of Universal Character Set Standards 4599 The previous section makes a case for using a universal character 4600 set. This section makes the case for using UTF-8 as the specific 4601 universal character set for the NFS version 4 protocol. 4603 [RFC2279] discusses UTF-* (UTF-8 and other UTF-XXX encodings), 4604 Unicode, and UCS-*. There are two standards bodies managing 4605 universal code sets: 4607 o ISO/IEC which has the standard 10646-1 4609 o Unicode which has the Unicode standard 4611 Both standards bodies have pledged to track each other's assignments 4612 of character codes. 4614 The following is a brief analysis of the various standards. 4616 UCS Universal Character Set. This is ISO/IEC 10646-1: "a 4617 multi-octet character set called the Universal Character 4618 Set (UCS), which encompasses most of the world's writing 4619 systems." 4621 UCS-2 a two octet per character encoding that addresses the first 4622 2^16 characters of UCS. Currently there are no UCS 4623 characters beyond that range. 4625 UCS-4 a four octet per character encoding that permits the 4626 encoding of up to 2^31 characters. 4628 UTF UTF is an abbreviation of the term "UCS transformation 4629 format" and is used in the naming of various standards for 4630 encoding of UCS characters as described below. 4632 UTF-1 Only historical interest; it has been removed from 10646-1 4634 Draft Specification NFS version 4 Protocol November 2001 4636 UTF-7 Encodes the entire "repertoire" of UCS "characters using 4637 only octets with the higher order bit clear". [RFC2152] 4638 describes UTF-7. UTF-7 accomplishes this by reserving one 4639 of the 7bit US-ASCII characters as a "shift" character to 4640 indicate non-US-ASCII characters. 4642 UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII 4643 characters are encoded as before unchanged. Any octet with 4644 the high bit cleared can only mean a US-ASCII character. 4645 The high bit set means that a UCS character is being 4646 encoded. 4648 UTF-16 Encodes UCS-4 characters into UCS-2 characters using a 4649 reserved range in UCS-2. 4651 Unicode Unicode and UCS-2 are the same; [RFC2279] states: 4653 Up to the present time, changes in Unicode and amendments 4654 to ISO/IEC 10646 have tracked each other, so that the 4655 character repertoires and code point assignments have 4656 remained in sync. The relevant standardization committees 4657 have committed to maintain this very useful synchronism. 4659 11.3. Difficulties with UCS-4, UCS-2, Unicode 4661 Adapting existing applications, and file systems to multi-octet 4662 schemes like UCS and Unicode can be difficult. A significant amount 4663 of code has been written to process streams of bytes. Also there are 4664 many existing stored objects described with 7 bit or 8 bit 4665 characters. Doubling or quadrupling the bandwidth and storage 4666 requirements seems like an expensive way to accomplish I18N. 4668 UCS-2 and Unicode are "only" 16 bits long. That might seem to be 4669 enough but, according to [Unicode1], 49,194 Unicode characters are 4670 already assigned. According to [Unicode2] there are still more 4671 languages that need to be added. 4673 11.4. UTF-8 and its solutions 4675 UTF-8 solves problems for NFS that exist with the use of UCS and 4676 Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way 4677 that will be compact for most users. The encoding table from UCS-4 to 4678 UTF-8, as copied from [RFC2279]: 4680 UCS-4 range (hex.) UTF-8 octet sequence (binary) 4681 0000 0000-0000 007F 0xxxxxxx 4682 0000 0080-0000 07FF 110xxxxx 10xxxxxx 4683 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 4685 Draft Specification NFS version 4 Protocol November 2001 4687 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 4688 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4689 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 4690 10xxxxxx 4692 See [RFC2279] for precise encoding and decoding rules. Note because 4693 of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account 4694 for the reserved range between D800 and DFFF. 4696 Note that the 16 bit UCS or Unicode characters require no more than 3 4697 octets to encode into UTF-8 4699 Interestingly, UTF-8 has room to handle characters larger than 31 4700 bits, because the leading octet of form: 4702 1111111x 4704 is not defined. If needed, ISO could either use that octet to 4705 indicate a sequence of an encoded 8 octet character, or perhaps use 4706 11111110 to permit the next octet to indicate an even more expandable 4707 character set. 4709 So using UTF-8 to represent character encodings means never having to 4710 run out of room. 4712 11.5. Normalization 4714 The client and server operating environments may differ in their 4715 policies and operational methods with respect to character 4716 normalization (See [Unicode1] for a discussion of normalization 4717 forms). This difference may also exist between applications on the 4718 same client. This adds to the difficulty of providing a single 4719 normalization policy for the protocol that allows for maximal 4720 interoperability. This issue is similar to the character case issues 4721 where the server may or may not support case insensitive file name 4722 matching and may or may not preserve the character case when storing 4723 file names. The protocol does not mandate a particular behavior but 4724 allows for the various permutations. 4726 The NFS version 4 protocol does not mandate the use of a particular 4727 normalization form at this time. A later revision of this 4728 specification may specify a particular normalization form. 4729 Therefore, the server and client can expect that they may receive 4730 unnormalized characters within protocol requests and responses. If 4731 the operating environment requires normalization, then the 4732 implementation must normalize the various UTF-8 encoded strings 4733 within the protocol before presenting the information to an 4734 application (at the client) or local file system (at the server). 4736 Draft Specification NFS version 4 Protocol November 2001 4738 12. Error Definitions 4740 NFS error numbers are assigned to failed operations within a compound 4741 request. A compound request contains a number of NFS operations that 4742 have their results encoded in sequence in a compound reply. The 4743 results of successful operations will consist of an NFS4_OK status 4744 followed by the encoded results of the operation. If an NFS 4745 operation fails, an error status will be entered in the reply and the 4746 compound request will be terminated. 4748 A description of each defined error follows: 4750 NFS4_OK Indicates the operation completed successfully. 4752 NFS4ERR_ACCES Permission denied. The caller does not have the 4753 correct permission to perform the requested 4754 operation. Contrast this with NFS4ERR_PERM, 4755 which restricts itself to owner or privileged 4756 user permission failures. 4758 NFS4ERR_ATTRNOTSUPP An attribute specified is not supported by the 4759 server. Does not apply to the GETATTR 4760 operation. 4762 NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed 4763 internal consistency checks. 4765 NFS4ERR_BADTYPE An attempt was made to create an object of a 4766 type not supported by the server. 4768 NFS4ERR_BAD_COOKIE READDIR cookie is stale. 4770 NFS4ERR_BAD_SEQID The sequence number in a locking request is 4771 neither the next expected number or the last 4772 number processed. 4774 NFS4ERR_BAD_STATEID A stateid generated by the current server 4775 instance, but which does not designate any 4776 locking state (either current or superseded) 4777 for a current lockowner-file pair, was used. 4779 NFS4ERR_BADXDR The server encountered an XDR decoding error 4780 while processing an operation. 4782 NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a 4783 client id is already in use by another client. 4785 NFS4ERR_DELAY The server initiated the request, but was not 4786 able to complete it in a timely fashion. The 4787 client should wait and then try the request 4789 Draft Specification NFS version 4 Protocol November 2001 4791 with a new RPC transaction ID. For example, 4792 this error should be returned from a server 4793 that supports hierarchical storage and receives 4794 a request to process a file that has been 4795 migrated. In this case, the server should start 4796 the immigration process and respond to client 4797 with this error. This error may also occur 4798 when a necessary delegation recall makes 4799 processing a request in a timely fashion 4800 impossible. 4802 NFS4ERR_DENIED An attempt to lock a file is denied. Since 4803 this may be a temporary condition, the client 4804 is encouraged to retry the lock request until 4805 the lock is accepted. 4807 NFS4ERR_DQUOT Resource (quota) hard limit exceeded. The 4808 user's resource limit on the server has been 4809 exceeded. 4811 NFS4ERR_EXIST File exists. The file specified already exists. 4813 NFS4ERR_EXPIRED A lease has expired that is being used in the 4814 current procedure. 4816 NFS4ERR_FBIG File too large. The operation would have caused 4817 a file to grow beyond the server's limit. 4819 NFS4ERR_FHEXPIRED The file handle provided is volatile and has 4820 expired at the server. 4822 NFS4ERR_GRACE The server is in its recovery or grace period 4823 which should match the lease period of the 4824 server. 4826 NFS4ERR_INVAL Invalid argument or unsupported argument for an 4827 operation. Two examples are attempting a 4828 READLINK on an object other than a symbolic 4829 link or attempting to SETATTR a time field on a 4830 server that does not support this operation. 4832 NFS4ERR_IO I/O error. A hard error (for example, a disk 4833 error) occurred while processing the requested 4834 operation. 4836 NFS4ERR_ISDIR Is a directory. The caller specified a 4837 directory in a non-directory operation. 4839 NFS4ERR_LEASE_MOVED A lease being renewed is associated with a file 4840 system that has been migrated to a new server. 4842 NFS4ERR_LOCKED A read or write operation was attempted on a 4844 Draft Specification NFS version 4 Protocol November 2001 4846 locked file. 4848 NFS4ERR_LOCK_RANGE A lock request is operating on a sub-range of a 4849 current lock for the lock owner and the server 4850 does not support this type of request. 4852 NFS4ERR_MINOR_VERS_MISMATCH 4853 The server has received a request that 4854 specifies an unsupported minor version. The 4855 server must return a COMPOUND4res with a zero 4856 length operations result array. 4858 NFS4ERR_MLINK Too many hard links. 4860 NFS4ERR_MOVED The filesystem which contains the current 4861 filehandle object has been relocated or 4862 migrated to another server. The client may 4863 obtain the new filesystem location by obtaining 4864 the "fs_locations" attribute for the current 4865 filehandle. For further discussion, refer to 4866 the section "Filesystem Migration or 4867 Relocation". 4869 NFS4ERR_NAMETOOLONG The filename in an operation was too long. 4871 NFS4ERR_NODEV No such device. 4873 NFS4ERR_NOENT No such file or directory. The file or 4874 directory name specified does not exist. 4876 NFS4ERR_NOFILEHANDLE The logical current file handle value has not 4877 been set properly. This may be a result of a 4878 malformed COMPOUND operation (i.e. no PUTFH or 4879 PUTROOTFH before an operation that requires the 4880 current file handle be set). 4882 NFS4ERR_NO_GRACE A reclaim of client state has fallen outside of 4883 the grace period of the server. As a result, 4884 the server can not guarantee that conflicting 4885 state has not been provided to another client. 4887 NFS4ERR_NOSPC No space left on device. The operation would 4888 have caused the server's file system to exceed 4889 its limit. 4891 NFS4ERR_NOTDIR Not a directory. The caller specified a non- 4892 directory in a directory operation. 4894 NFS4ERR_NOTEMPTY An attempt was made to remove a directory that 4895 was not empty. 4897 NFS4ERR_NOTSUPP Operation is not supported. 4899 Draft Specification NFS version 4 Protocol November 2001 4901 NFS4ERR_NOT_SAME This error is returned by the VERIFY operation 4902 to signify that the attributes compared were 4903 not the same as provided in the client's 4904 request. 4906 NFS4ERR_NXIO I/O error. No such device or address. 4908 NFS4ERR_OLD_STATEID A stateid which designates the locking state 4909 for a lockowner-file at an earlier time was 4910 used. 4912 NFS4ERR_PERM Not owner. The operation was not allowed 4913 because the caller is either not a privileged 4914 user (root) or not the owner of the target of 4915 the operation. 4917 NFS4ERR_READDIR_NOSPC The encoded response to a READDIR request 4918 exceeds the size limit set by the initial 4919 request. 4921 NFS4ERR_RECLAIM_BAD The reclaim provided by the client does not 4922 match any of the server's state consistency 4923 checks and is bad. 4925 NFS4ERR_RECLAIM_CONFLICT 4926 The reclaim provided by the client has 4927 encountered a conflict and can not be provided. 4928 Potentially indicates a misbehaving client. 4930 NFS4ERR_RESOURCE For the processing of the COMPOUND procedure, 4931 the server may exhaust available resources and 4932 can not continue processing procedures within 4933 the COMPOUND operation. This error will be 4934 returned from the server in those instances of 4935 resource exhaustion related to the processing 4936 of the COMPOUND procedure. 4938 NFS4ERR_ROFS Read-only file system. A modifying operation 4939 was attempted on a read-only file system. 4941 NFS4ERR_SAME This error is returned by the NVERIFY operation 4942 to signify that the attributes compared were 4943 the same as provided in the client's request. 4945 NFS4ERR_SERVERFAULT An error occurred on the server which does not 4946 map to any of the legal NFS version 4 protocol 4947 error values. The client should translate this 4948 into an appropriate error. UNIX clients may 4949 choose to translate this to EIO. 4951 NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share 4952 reservation has failed because of a share 4954 Draft Specification NFS version 4 Protocol November 2001 4956 conflict. 4958 NFS4ERR_STALE Invalid file handle. The file handle given in 4959 the arguments was invalid. The file referred to 4960 by that file handle no longer exists or access 4961 to it has been revoked. 4963 NFS4ERR_STALE_CLIENTID A clientid not recognized by the server was 4964 used in a locking or SETCLIENTID_CONFIRM 4965 request. 4967 NFS4ERR_STALE_STATEID A stateid generated by an earlier server 4968 instance was used. 4970 NFS4ERR_SYMLINK The current file handle provided for a LOOKUP 4971 is not a directory but a symbolic link. Also 4972 used if the final component of the OPEN path is 4973 a symbolic link. 4975 NFS4ERR_TOOSMALL Buffer or request is too small. 4977 NFS4ERR_WRONGSEC The security mechanism being used by the client 4978 for the procedure does not match the server's 4979 security policy. The client should change the 4980 security mechanism being used and retry the 4981 operation. 4983 NFS4ERR_XDEV Attempt to do a cross-device hard link. 4985 Draft Specification NFS version 4 Protocol November 2001 4987 13. NFS Version 4 Requests 4989 For the NFS version 4 RPC program, there are two traditional RPC 4990 procedures: NULL and COMPOUND. All other functionality is defined as 4991 a set of operations and these operations are defined in normal 4992 XDR/RPC syntax and semantics. However, these operations are 4993 encapsulated within the COMPOUND procedure. This requires that the 4994 client combine one or more of the NFS version 4 operations into a 4995 single request. 4997 The NFS4_CALLBACK program is used to provide server to client 4998 signaling and is constructed in a similar fashion as the NFS version 4999 4 program. The procedures CB_NULL and CB_COMPOUND are defined in the 5000 same way as NULL and COMPOUND are within the NFS program. The 5001 CB_COMPOUND request also encapsulates the remaining operations of the 5002 NFS4_CALLBACK program. There is no predefined RPC program number for 5003 the NFS4_CALLBACK program. It is up to the client to specify a 5004 program number in the "transient" program range. The program and 5005 port number of the NFS4_CALLBACK program are provided by the client 5006 as part of the SETCLIENTID operation and therefore is fixed for the 5007 life of the client instantiation. 5009 13.1. Compound Procedure 5011 The COMPOUND procedure provides the opportunity for better 5012 performance within high latency networks. The client can avoid 5013 cumulative latency of multiple RPCs by combining multiple dependent 5014 operations into a single COMPOUND procedure. A compound operation 5015 may provide for protocol simplification by allowing the client to 5016 combine basic procedures into a single request that is customized for 5017 the client's environment. 5019 The CB_COMPOUND procedure precisely parallels the features of 5020 COMPOUND as described above. 5022 The basics of the COMPOUND procedures construction is: 5024 +-----------+-----------+-----------+-- 5025 | op + args | op + args | op + args | 5026 +-----------+-----------+-----------+-- 5028 and the reply looks like this: 5030 +------------+-----------------------+-----------------------+-- 5031 |last status | status + op + results | status + op + results | 5032 +------------+-----------------------+-----------------------+-- 5034 13.2. Evaluation of a Compound Request 5036 The server will process the COMPOUND procedure by evaluating each of 5038 Draft Specification NFS version 4 Protocol November 2001 5040 the operations within the COMPOUND procedure in order. Each 5041 component operation consists of a 32 bit operation code, followed by 5042 the argument of length determined by the type of operation. The 5043 results of each operation are encoded in sequence into a reply 5044 buffer. The results of each operation are preceded by the opcode and 5045 a status code (normally zero). If an operation results in a non-zero 5046 status code, the status will be encoded and evaluation of the 5047 compound sequence will halt and the reply will be returned. Note 5048 that evaluation stops even in the event of "non error" conditions 5049 such as NFS4ERR_SAME. 5051 There are no atomicity requirements for the operations contained 5052 within the COMPOUND procedure. The operations being evaluated as 5053 part of a COMPOUND request may be evaluated simultaneously with other 5054 COMPOUND requests that the server receives. 5056 It is the client's responsibility for recovering from any partially 5057 completed COMPOUND procedure. Partially completed COMPOUND 5058 procedures may occur at any point due to errors such as 5059 NFS4ERR_RESOURCE and NFS4ERR_LONG_DELAY. This may occur even given 5060 an otherwise valid operation string. Further, a server reboot which 5061 occurs in the middle of processing a COMPOUND procedure may leave the 5062 client with the difficult task of determining how far COMPOUND 5063 processing has proceeded. Therefore, the client should avoid overly 5064 complex COMPOUND procedures in the event of the failure of an 5065 operation within the procedure. 5067 Each operation assumes a "current" and "saved" filehandle that is 5068 available as part of the execution context of the compound request. 5069 Operations may set, change, or return the current filehandle. The 5070 "saved" filehandle is used for temporary storage of a filehandle 5071 value and as operands for the RENAME and LINK operations. 5073 13.3. Synchronous Modifying Operations 5075 NFS version 4 operations that modify the file system are synchronous. 5076 When an operation is successfully completed at the server, the client 5077 can depend that any data associated with the request is now on stable 5078 storage (the one exception is in the case of the file data in a WRITE 5079 operation with the UNSTABLE option specified). 5081 This implies that any previous operations within the same compound 5082 request are also reflected in stable storage. This behavior enables 5083 the client's ability to recover from a partially executed compound 5084 request which may resulted from the failure of the server. For 5085 example, if a compound request contains operations A and B and the 5086 server is unable to send a response to the client, depending on the 5087 progress the server made in servicing the request the result of both 5088 operations may be reflected in stable storage or just operation A may 5089 be reflected. The server must not have just the results of operation 5090 B in stable storage. 5092 Draft Specification NFS version 4 Protocol November 2001 5094 13.4. Operation Values 5096 The operations encoded in the COMPOUND procedure are identified by 5097 operation values. To avoid overlap with the RPC procedure numbers, 5098 operations 0 (zero) and 1 are not defined. Operation 2 is not 5099 defined but reserved for future use with minor versioning. 5101 Draft Specification NFS version 4 Protocol November 2001 5103 14. NFS Version 4 Procedures 5105 14.1. Procedure 0: NULL - No Operation 5107 SYNOPSIS 5109 5111 ARGUMENT 5113 void; 5115 RESULT 5117 void; 5119 DESCRIPTION 5121 Standard NULL procedure. Void argument, void response. This 5122 procedure has no functionality associated with it. Because of this 5123 it is sometimes used to measure the overhead of processing a 5124 service request. Therefore, the server should ensure that no 5125 unnecessary work is done in servicing this procedure. 5127 ERRORS 5129 None. 5131 Draft Specification NFS version 4 Protocol November 2001 5133 14.2. Procedure 1: COMPOUND - Compound Operations 5135 SYNOPSIS 5137 compoundargs -> compoundres 5139 ARGUMENT 5141 union nfs_argop4 switch (nfs_opnum4 argop) { 5142 case : ; 5143 ... 5144 }; 5146 struct COMPOUND4args { 5147 utf8string tag; 5148 uint32_t minorversion; 5149 nfs_argop4 argarray<>; 5150 }; 5152 RESULT 5154 union nfs_resop4 switch (nfs_opnum4 resop){ 5155 case : ; 5156 ... 5157 }; 5159 struct COMPOUND4res { 5160 nfsstat4 status; 5161 utf8string tag; 5162 nfs_resop4 resarray<>; 5163 }; 5165 DESCRIPTION 5167 The COMPOUND procedure is used to combine one or more of the NFS 5168 operations into a single RPC request. The main NFS RPC program has 5169 two main procedures: NULL and COMPOUND. All other operations use 5170 the COMPOUND procedure as a wrapper. 5172 The COMPOUND procedure is used to combine individual operations 5173 into a single RPC request. The server interprets each of the 5174 operations in turn. If an operation is executed by the server and 5175 the status of that operation is NFS4_OK, then the next operation in 5176 the COMPOUND procedure is executed. The server continues this 5177 process until there are no more operations to be executed or one of 5178 the operations has a status value other than NFS4_OK. 5180 Draft Specification NFS version 4 Protocol November 2001 5182 In the processing of the COMPOUND procedure, the server may find 5183 that it does not have the available resources to execute any or all 5184 of the operations within the COMPOUND sequence. In this case, the 5185 error NFS4ERR_RESOURCE will be returned for the particular 5186 operation within the COMPOUND procedure where the resource 5187 exhaustion occurred. This assumes that all previous operations 5188 within the COMPOUND sequence have been evaluated successfully. The 5189 results for all of the evaluated operations must be returned to the 5190 client. 5192 The server will generally choose between two methods of decoding 5193 the client's request. The first would be the traditional one pass 5194 XDR decode. If there is an XDR decoding error in this case, the 5195 RPC XDR decode error would be returned. The second method would be 5196 to make an initial pass to decode the basic COMPOUND request and 5197 then to XDR decode the individual operations; the most interesting 5198 is the decode of attributes. In this case, the server may 5199 encounter an XDR decode error during the second pass. In this 5200 case, the server would return the error NFS4ERR_BADXDR to signify 5201 the decode error. 5203 The COMPOUND arguments contain a "minorversion" field. The initial 5204 and default value for this field is 0 (zero). This field will be 5205 used by future minor versions such that the client can communicate 5206 to the server what minor version is being requested. If the server 5207 receives a COMPOUND procedure with a minorversion field value that 5208 it does not support, the server MUST return an error of 5209 NFS4ERR_MINOR_VERS_MISMATCH and a zero length resultdata array. 5211 Contained within the COMPOUND results is a "status" field. If the 5212 results array length is non-zero, this status must be equivalent to 5213 the status of the last operation that was executed within the 5214 COMPOUND procedure. Therefore, if an operation incurred an error 5215 then the "status" value will be the same error value as is being 5216 returned for the operation that failed. 5218 Note that operations, 0 (zero) and 1 (one) are not defined for the 5219 COMPOUND procedure. If the server receives an operation array with 5220 either of these included, an error of NFS4ERR_NOTSUPP must be 5221 returned. Operation 2 is not defined but reserved for future 5222 definition and use with minor versioning. If the server receives a 5223 operation array that contains operation 2 and the minorversion 5224 field has a value of 0 (zero), an error of NFS4ERR_NOTSUPP is 5225 returned. If an operation array contains an operation 2 and the 5226 minorversion field is non-zero and the server does not support the 5227 minor version, the server returns an error of 5228 NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the 5229 NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other 5230 errors. 5232 It is possible that the server receives a request that contains an 5233 operation that is beyond the last defined operation (e.g. 5235 Draft Specification NFS version 4 Protocol November 2001 5237 OP_WRITE). In this case, the server obviously will fail the 5238 unknown operation. If this occurs, the server will return an 5239 operation "opcode" that is 1 greater than the largest defined 5240 operation. For example, the server would return an opcode of 5241 OP_WRITE + 1. The server would then return a status of 5242 NFS4ERR_NOTSUPP to indicate an operation that is not defined and 5243 therefore not supported. 5245 IMPLEMENTATION 5247 Note that the definition of the "tag" in both the request and 5248 response are left to the implementor. It may be used to summarize 5249 the content of the compound request for the benefit of packet 5250 sniffers and engineers debugging implementations. 5252 Since an error of any type may occur after only a portion of the 5253 operations have been evaluated, the client must be prepared to 5254 recover from any failure. If the source of an NFS4ERR_RESOURCE 5255 error was a complex or lengthy set of operations, it is likely that 5256 if the number of operations were reduced the server would be able 5257 to evaluate them successfully. Therefore, the client is 5258 responsible for dealing with this type of complexity in recovery. 5260 ERRORS 5262 All errors defined in the protocol 5264 Draft Specification NFS version 4 Protocol November 2001 5266 14.2.1. Operation 3: ACCESS - Check Access Rights 5268 SYNOPSIS 5270 (cfh), accessreq -> supported, accessrights 5272 ARGUMENT 5274 const ACCESS4_READ = 0x00000001; 5275 const ACCESS4_LOOKUP = 0x00000002; 5276 const ACCESS4_MODIFY = 0x00000004; 5277 const ACCESS4_EXTEND = 0x00000008; 5278 const ACCESS4_DELETE = 0x00000010; 5279 const ACCESS4_EXECUTE = 0x00000020; 5281 struct ACCESS4args { 5282 /* CURRENT_FH: object */ 5283 uint32_t access; 5284 }; 5286 RESULT 5288 struct ACCESS4resok { 5289 uint32_t supported; 5290 uint32_t access; 5291 }; 5293 union ACCESS4res switch (nfsstat4 status) { 5294 case NFS4_OK: 5295 ACCESS4resok resok4; 5296 default: 5297 void; 5298 }; 5300 DESCRIPTION 5302 ACCESS determines the access rights that a user, as identified by 5303 the credentials in the RPC request, has with respect to the file 5304 system object specified by the current filehandle. The client 5305 encodes the set of access rights that are to be checked in the bit 5306 mask "access". The server checks the permissions encoded in the 5307 bit mask. If a status of NFS4_OK is returned, two bit masks are 5308 included in the response. The first, "supported", represents the 5309 access rights for which the server can verify reliably. The 5310 second, "access", represents the access rights available to the 5311 user for the filehandle provided. On success, the current 5312 filehandle retains its value. 5314 Draft Specification NFS version 4 Protocol November 2001 5316 Note that the supported field will contain only as many values as 5317 was originally sent in the arguments. For example, if the client 5318 sends an ACCESS operation with only the ACCESS4_READ value set and 5319 the server supports this value, the server will return only 5320 ACCESS4_READ even if it could have reliably checked other values. 5322 The results of this operation are necessarily advisory in nature. 5323 A return status of NFS4_OK and the appropriate bit set in the bit 5324 mask does not imply that such access will be allowed to the file 5325 system object in the future. This is because access rights can be 5326 revoked by the server at any time. 5328 The following access permissions may be requested: 5330 ACCESS4_READ Read data from file or read a directory. 5332 ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- 5333 directory objects). 5335 ACCESS4_MODIFY Rewrite existing file data or modify existing 5336 directory entries. 5338 ACCESS4_EXTEND Write new data or add directory entries. 5340 ACCESS4_DELETE Delete an existing directory entry (no meaning for 5341 non-directory objects). 5343 ACCESS4_EXECUTE Execute file (no meaning for a directory). 5345 On success, the current filehandle retains its value. 5347 IMPLEMENTATION 5349 For the NFS version 4 protocol, the use of the ACCESS procedure 5350 when opening a regular file is deprecated in favor of using OPEN. 5352 In general, it is not sufficient for the client to attempt to 5353 deduce access permissions by inspecting the uid, gid, and mode 5354 fields in the file attributes or by attempting to interpret the 5355 contents of the ACL attribute. This is because the server may 5356 perform uid or gid mapping or enforce additional access control 5357 restrictions. It is also possible that the server may not be in 5358 the same ID space as the client. In these cases (and perhaps 5359 others), the client can not reliably perform an access check with 5360 only current file attributes. 5362 In the NFS version 2 protocol, the only reliable way to determine 5363 whether an operation was allowed was to try it and see if it 5364 succeeded or failed. Using the ACCESS procedure in the NFS version 5365 4 protocol, the client can ask the server to indicate whether or 5366 not one or more classes of operations are permitted. The ACCESS 5368 Draft Specification NFS version 4 Protocol November 2001 5370 operation is provided to allow clients to check before doing a 5371 series of operations which will result in an access failure. The 5372 OPEN operation provides a point where the server can verify access 5373 to the file object and method to return that information to the 5374 client. The ACCESS operation is still useful for directory 5375 operations or for use in the case the UNIX API "access" is used on 5376 the client. 5378 The information returned by the server in response to an ACCESS 5379 call is not permanent. It was correct at the exact time that the 5380 server performed the checks, but not necessarily afterwards. The 5381 server can revoke access permission at any time. 5383 The client should use the effective credentials of the user to 5384 build the authentication information in the ACCESS request used to 5385 determine access rights. It is the effective user and group 5386 credentials that are used in subsequent read and write operations. 5388 Many implementations do not directly support the ACCESS4_DELETE 5389 permission. Operating systems like UNIX will ignore the 5390 ACCESS4_DELETE bit if set on an access request on a non-directory 5391 object. In these systems, delete permission on a file is 5392 determined by the access permissions on the directory in which the 5393 file resides, instead of being determined by the permissions of the 5394 file itself. Therefore, the mask returned enumerating which access 5395 rights can be determined will have the ACCESS4_DELETE value set to 5396 0. This indicates to the client that the server was unable to 5397 check that particular access right. The ACCESS4_DELETE bit in the 5398 access mask returned will then be ignored by the client. 5400 ERRORS 5402 NFS4ERR_ACCES 5403 NFS4ERR_BADHANDLE 5404 NFS4ERR_BADXDR 5405 NFS4ERR_DELAY 5406 NFS4ERR_FHEXPIRED 5407 NFS4ERR_IO 5408 NFS4ERR_MOVED 5409 NFS4ERR_NOFILEHANDLE 5410 NFS4ERR_RESOURCE 5411 NFS4ERR_SERVERFAULT 5412 NFS4ERR_STALE 5413 NFS4ERR_WRONGSEC 5415 Draft Specification NFS version 4 Protocol November 2001 5417 14.2.2. Operation 4: CLOSE - Close File 5419 SYNOPSIS 5421 (cfh), seqid, stateid -> stateid 5423 ARGUMENT 5425 struct CLOSE4args { 5426 /* CURRENT_FH: object */ 5427 seqid4 seqid 5428 stateid4 stateid; 5429 }; 5431 RESULT 5433 union CLOSE4res switch (nfsstat4 status) { 5434 case NFS4_OK: 5435 stateid4 stateid; 5436 default: 5437 void; 5438 }; 5440 DESCRIPTION 5442 The CLOSE operation releases share reservations for the file as 5443 specified by the current filehandle. The share reservations and 5444 other state information released at the server as a result of this 5445 CLOSE is only associated with the supplied stateid. The sequence 5446 id provides for the correct ordering. State associated with other 5447 OPENs is not affected. 5449 If record locks are held, the client SHOULD release all locks 5450 before issuing a CLOSE. The server MAY free all outstanding locks 5451 on CLOSE but some servers may not support the CLOSE of a file that 5452 still has record locks held. The server MUST return failure if any 5453 locks would exist after the CLOSE. 5455 On success, the current filehandle retains its value. 5457 IMPLEMENTATION 5459 ERRORS 5461 Draft Specification NFS version 4 Protocol November 2001 5463 NFS4ERR_BADHANDLE 5464 NFS4ERR_BAD_SEQID 5465 NFS4ERR_BAD_STATEID 5466 NFS4ERR_BADXDR 5467 NFS4ERR_DELAY 5468 NFS4ERR_EXPIRED 5469 NFS4ERR_FHEXPIRED 5470 NFS4ERR_GRACE 5471 NFS4ERR_INVAL 5472 NFS4ERR_ISDIR 5473 NFS4ERR_LEASE_MOVED 5474 NFS4ERR_LOCKS_HELD 5475 NFS4ERR_MOVED 5476 NFS4ERR_NOFILEHANDLE 5477 NFS4ERR_OLD_STATEID 5478 NFS4ERR_RESOURCE 5479 NFS4ERR_SERVERFAULT 5480 NFS4ERR_STALE 5481 NFS4ERR_STALE_STATEID 5483 Draft Specification NFS version 4 Protocol November 2001 5485 14.2.3. Operation 5: COMMIT - Commit Cached Data 5487 SYNOPSIS 5489 (cfh), offset, count -> verifier 5491 ARGUMENT 5493 struct COMMIT4args { 5494 /* CURRENT_FH: file */ 5495 offset4 offset; 5496 count4 count; 5497 }; 5499 RESULT 5501 struct COMMIT4resok { 5502 verifier4 writeverf; 5503 }; 5505 union COMMIT4res switch (nfsstat4 status) { 5506 case NFS4_OK: 5507 COMMIT4resok resok4; 5508 default: 5509 void; 5510 }; 5512 DESCRIPTION 5514 The COMMIT operation forces or flushes data to stable storage for 5515 the file specified by the current file handle. The flushed data is 5516 that which was previously written with a WRITE operation which had 5517 the stable field set to UNSTABLE4. 5519 The offset specifies the position within the file where the flush 5520 is to begin. An offset value of 0 (zero) means to flush data 5521 starting at the beginning of the file. The count specifies the 5522 number of bytes of data to flush. If count is 0 (zero), a flush 5523 from offset to the end of the file is done. 5525 The server returns a write verifier upon successful completion of 5526 the COMMIT. The write verifier is used by the client to determine 5527 if the server has restarted or rebooted between the initial 5528 WRITE(s) and the COMMIT. The client does this by comparing the 5529 write verifier returned from the initial writes and the verifier 5530 returned by the COMMIT procedure. The server must vary the value 5531 of the write verifier at each server event or instantiation that 5532 may lead to a loss of uncommitted data. Most commonly this occurs 5533 when the server is rebooted; however, other events at the server 5535 Draft Specification NFS version 4 Protocol November 2001 5537 may result in uncommitted data loss as well. 5539 On success, the current filehandle retains its value. 5541 IMPLEMENTATION 5543 The COMMIT procedure is similar in operation and semantics to the 5544 POSIX fsync(2) system call that synchronizes a file's state with 5545 the disk (file data and metadata is flushed to disk or stable 5546 storage). COMMIT performs the same operation for a client, flushing 5547 any unsynchronized data and metadata on the server to the server's 5548 disk or stable storage for the specified file. Like fsync(2), it 5549 may be that there is some modified data or no modified data to 5550 synchronize. The data may have been synchronized by the server's 5551 normal periodic buffer synchronization activity. COMMIT should 5552 return NFS4_OK, unless there has been an unexpected error. 5554 COMMIT differs from fsync(2) in that it is possible for the client 5555 to flush a range of the file (most likely triggered by a buffer- 5556 reclamation scheme on the client before file has been completely 5557 written). 5559 The server implementation of COMMIT is reasonably simple. If the 5560 server receives a full file COMMIT request, that is starting at 5561 offset 0 and count 0, it should do the equivalent of fsync()'ing 5562 the file. Otherwise, it should arrange to have the cached data in 5563 the range specified by offset and count to be flushed to stable 5564 storage. In both cases, any metadata associated with the file must 5565 be flushed to stable storage before returning. It is not an error 5566 for there to be nothing to flush on the server. This means that 5567 the data and metadata that needed to be flushed have already been 5568 flushed or lost during the last server failure. 5570 The client implementation of COMMIT is a little more complex. 5571 There are two reasons for wanting to commit a client buffer to 5572 stable storage. The first is that the client wants to reuse a 5573 buffer. In this case, the offset and count of the buffer are sent 5574 to the server in the COMMIT request. The server then flushes any 5575 cached data based on the offset and count, and flushes any metadata 5576 associated with the file. It then returns the status of the flush 5577 and the write verifier. The other reason for the client to 5578 generate a COMMIT is for a full file flush, such as may be done at 5579 close. In this case, the client would gather all of the buffers 5580 for this file that contain uncommitted data, do the COMMIT 5581 operation with an offset of 0 and count of 0, and then free all of 5582 those buffers. Any other dirty buffers would be sent to the server 5583 in the normal fashion. 5585 After a buffer is written by the client with the stable parameter 5586 set to UNSTABLE4, the buffer must be considered as modified by the 5587 client until the buffer has either been flushed via a COMMIT 5589 Draft Specification NFS version 4 Protocol November 2001 5591 operation or written via a WRITE operation with stable parameter 5592 set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer 5593 from being freed and reused before the data can be flushed to 5594 stable storage on the server. 5596 When a response is returned from either a WRITE or a COMMIT 5597 operation and it contains a write verifier that is different than 5598 previously returned by the server, the client will need to 5599 retransmit all of the buffers containing uncommitted cached data to 5600 the server. How this is to be done is up to the implementor. If 5601 there is only one buffer of interest, then it should probably be 5602 sent back over in a WRITE request with the appropriate stable 5603 parameter. If there is more than one buffer, it might be 5604 worthwhile retransmitting all of the buffers in WRITE requests with 5605 the stable parameter set to UNSTABLE4 and then retransmitting the 5606 COMMIT operation to flush all of the data on the server to stable 5607 storage. The timing of these retransmissions is left to the 5608 implementor. 5610 The above description applies to page-cache-based systems as well 5611 as buffer-cache-based systems. In those systems, the virtual 5612 memory system will need to be modified instead of the buffer cache. 5614 ERRORS 5616 NFS4ERR_ACCES 5617 NFS4ERR_BADHANDLE 5618 NFS4ERR_BADXDR 5619 NFS4ERR_FHEXPIRED 5620 NFS4ERR_IO 5621 NFS4ERR_ISDIR 5622 NFS4ERR_LOCKED 5623 NFS4ERR_MOVED 5624 NFS4ERR_NOFILEHANDLE 5625 NFS4ERR_RESOURCE 5626 NFS4ERR_ROFS 5627 NFS4ERR_SERVERFAULT 5628 NFS4ERR_STALE 5629 NFS4ERR_WRONGSEC 5631 Draft Specification NFS version 4 Protocol November 2001 5633 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 5635 SYNOPSIS 5637 (cfh), name, type -> (cfh), change_info 5639 ARGUMENT 5641 union createtype4 switch (nfs_ftype4 type) { 5642 case NF4LNK: 5643 linktext4 linkdata; 5644 case NF4BLK: 5645 case NF4CHR: 5646 specdata4 devdata; 5647 case NF4SOCK: 5648 case NF4FIFO: 5649 case NF4DIR: 5650 void; 5651 }; 5653 struct CREATE4args { 5654 /* CURRENT_FH: directory for creation */ 5655 component4 objname; 5656 createtype4 objtype; 5657 }; 5659 RESULT 5661 struct CREATE4resok { 5662 change_info4 cinfo; 5663 }; 5665 union CREATE4res switch (nfsstat4 status) { 5666 case NFS4_OK: 5667 CREATE4resok resok4; 5668 default: 5669 void; 5670 }; 5672 DESCRIPTION 5674 The CREATE operation creates a non-regular file object in a 5675 directory with a given name. The OPEN procedure MUST be used to 5676 create a regular file. 5678 The objname specifies the name for the new object. If the objname 5679 has a length of 0 (zero), the error NFS4ERR_INVAL will be returned. 5680 The objtype determines the type of object to be created: directory, 5681 symlink, etc. 5683 Draft Specification NFS version 4 Protocol November 2001 5685 If an object of the same name already exists in the directory, the 5686 server will return the error NFS4ERR_EXIST. 5688 For the directory where the new file object was created, the server 5689 returns change_info4 information in cinfo. With the atomic field 5690 of the change_info4 struct, the server will indicate if the before 5691 and after change attributes were obtained atomically with respect 5692 to the file object creation. 5694 If the objname has a length of 0 (zero), or if objname does not 5695 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5696 returned. 5698 The current filehandle is replaced by that of the new object. 5700 IMPLEMENTATION 5702 If the client desires to set attribute values after the create, a 5703 SETATTR operation can be added to the COMPOUND request so that the 5704 appropriate attributes will be set. 5706 ERRORS 5708 NFS4ERR_ACCES 5709 NFS4ERR_ATTRNOTSUPP 5710 NFS4ERR_BADHANDLE 5711 NFS4ERR_BADTYPE 5712 NFS4ERR_BADXDR 5713 NFS4ERR_DQUOT 5714 NFS4ERR_EXIST 5715 NFS4ERR_FHEXPIRED 5716 NFS4ERR_INVAL 5717 NFS4ERR_IO 5718 NFS4ERR_MOVED 5719 NFS4ERR_NAMETOOLONG 5720 NFS4ERR_NOFILEHANDLE 5721 NFS4ERR_NOSPC 5722 NFS4ERR_NOTDIR 5723 NFS4ERR_NOTSUPP 5724 NFS4ERR_RESOURCE 5725 NFS4ERR_ROFS 5726 NFS4ERR_SERVERFAULT 5727 NFS4ERR_STALE 5728 NFS4ERR_WRONGSEC 5730 Draft Specification NFS version 4 Protocol November 2001 5732 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery 5734 SYNOPSIS 5736 clientid -> 5738 ARGUMENT 5740 struct DELEGPURGE4args { 5741 clientid4 clientid; 5742 }; 5744 RESULT 5746 struct DELEGPURGE4res { 5747 nfsstat4 status; 5748 }; 5750 DESCRIPTION 5752 Purges all of the delegations awaiting recovery for a given client. 5753 This is useful for clients which do not commit delegation 5754 information to stable storage to indicate that conflicting requests 5755 need not be delayed by the server awaiting recovery of delegation 5756 information. 5758 This operation should be used by clients that record delegation 5759 information on stable storage on the client. In this case, 5760 DELEGPURGE should be issued immediately after doing delegation 5761 recovery on all delegations know to the client. Doing so will 5762 notify the server that no additional delegations for the client 5763 will be recovered allowing it to free resources, and avoid delaying 5764 other clients who make requests that conflict with the unrecovered 5765 delegations. The set of delegations known to the server and the 5766 client may be different. The reason for this is that a client may 5767 fail after making a request which resulted in delegation but before 5768 it received the results and committed them to the client's stable 5769 storage. 5771 ERRORS 5773 NFS4ERR_BADXDR 5774 NFS4ERR_RESOURCE 5775 NFS4ERR_SERVERFAULT 5776 NFS4ERR_STALE_CLIENTID 5778 Draft Specification NFS version 4 Protocol November 2001 5780 14.2.6. Operation 8: DELEGRETURN - Return Delegation 5782 SYNOPSIS 5784 stateid -> 5786 ARGUMENT 5788 struct DELEGRETURN4args { 5789 stateid4 stateid; 5790 }; 5792 RESULT 5794 struct DELEGRETURN4res { 5795 nfsstat4 status; 5796 }; 5798 DESCRIPTION 5800 Returns the delegation represented by the given stateid. 5802 ERRORS 5804 NFS4ERR_BAD_STATEID 5805 NFS4ERR_BADXDR 5806 NFS4ERR_OLD_STATEID 5807 NFS4ERR_RESOURCE 5808 NFS4ERR_SERVERFAULT 5809 NFS4ERR_STALE_STATEID 5811 Draft Specification NFS version 4 Protocol November 2001 5813 14.2.7. Operation 9: GETATTR - Get Attributes 5815 SYNOPSIS 5817 (cfh), attrbits -> attrbits, attrvals 5819 ARGUMENT 5821 struct GETATTR4args { 5822 /* CURRENT_FH: directory or file */ 5823 bitmap4 attr_request; 5824 }; 5826 RESULT 5828 struct GETATTR4resok { 5829 fattr4 obj_attributes; 5830 }; 5832 union GETATTR4res switch (nfsstat4 status) { 5833 case NFS4_OK: 5834 GETATTR4resok resok4; 5835 default: 5836 void; 5837 }; 5839 DESCRIPTION 5841 The GETATTR operation will obtain attributes for the file system 5842 object specified by the current filehandle. The client sets a bit 5843 in the bitmap argument for each attribute value that it would like 5844 the server to return. The server returns an attribute bitmap that 5845 indicates the attribute values for which it was able to return, 5846 followed by the attribute values ordered lowest attribute number 5847 first. 5849 The server must return a value for each attribute that the client 5850 requests if the attribute is supported by the server. If the 5851 server does not support an attribute or cannot approximate a useful 5852 value then it must not return the attribute value and must not set 5853 the attribute bit in the result bitmap. The server must return an 5854 error if it supports an attribute but cannot obtain its value. In 5855 that case no attribute values will be returned. 5857 All servers must support the mandatory attributes as specified in 5858 the section "File Attributes". 5860 On success, the current filehandle retains its value. 5862 Draft Specification NFS version 4 Protocol November 2001 5864 IMPLEMENTATION 5866 ERRORS 5868 NFS4ERR_ACCES 5869 NFS4ERR_BADHANDLE 5870 NFS4ERR_BADXDR 5871 NFS4ERR_DELAY 5872 NFS4ERR_FHEXPIRED 5873 NFS4ERR_INVAL 5874 NFS4ERR_IO 5875 NFS4ERR_MOVED 5876 NFS4ERR_NOFILEHANDLE 5877 NFS4ERR_RESOURCE 5878 NFS4ERR_SERVERFAULT 5879 NFS4ERR_STALE 5880 NFS4ERR_WRONGSEC 5882 Draft Specification NFS version 4 Protocol November 2001 5884 14.2.8. Operation 10: GETFH - Get Current Filehandle 5886 SYNOPSIS 5888 (cfh) -> filehandle 5890 ARGUMENT 5892 /* CURRENT_FH: */ 5893 void; 5895 RESULT 5897 struct GETFH4resok { 5898 nfs_fh4 object; 5899 }; 5901 union GETFH4res switch (nfsstat4 status) { 5902 case NFS4_OK: 5903 GETFH4resok resok4; 5904 default: 5905 void; 5906 }; 5908 DESCRIPTION 5910 This operation returns the current filehandle value. 5912 On success, the current filehandle retains its value. 5914 IMPLEMENTATION 5916 Operations that change the current filehandle like LOOKUP or CREATE 5917 do not automatically return the new filehandle as a result. For 5918 instance, if a client needs to lookup a directory entry and obtain 5919 its filehandle then the following request is needed. 5921 PUTFH (directory filehandle) 5922 LOOKUP (entry name) 5923 GETFH 5925 ERRORS 5927 NFS4ERR_BADHANDLE 5928 NFS4ERR_FHEXPIRED 5929 NFS4ERR_MOVED 5931 Draft Specification NFS version 4 Protocol November 2001 5933 NFS4ERR_NOFILEHANDLE 5934 NFS4ERR_RESOURCE 5935 NFS4ERR_SERVERFAULT 5936 NFS4ERR_STALE 5937 NFS4ERR_WRONGSEC 5939 Draft Specification NFS version 4 Protocol November 2001 5941 14.2.9. Operation 11: LINK - Create Link to a File 5943 SYNOPSIS 5945 (sfh), (cfh), newname -> (cfh), change_info 5947 ARGUMENT 5949 struct LINK4args { 5950 /* SAVED_FH: source object */ 5951 /* CURRENT_FH: target directory */ 5952 component4 newname; 5953 }; 5955 RESULT 5957 struct LINK4resok { 5958 change_info4 cinfo; 5959 }; 5961 union LINK4res switch (nfsstat4 status) { 5962 case NFS4_OK: 5963 LINK4resok resok4; 5964 default: 5965 void; 5966 }; 5968 DESCRIPTION 5970 The LINK operation creates an additional newname for the file 5971 represented by the saved filehandle, as set by the SAVEFH 5972 operation, in the directory represented by the current filehandle. 5973 The existing file and the target directory must reside within the 5974 same file system on the server. On success, the current filehandle 5975 will continue to be the target directory. 5977 For the target directory, the server returns change_info4 5978 information in cinfo. With the atomic field of the change_info4 5979 struct, the server will indicate if the before and after change 5980 attributes were obtained atomically with respect to the link 5981 creation. 5983 If the newname has a length of 0 (zero), or if newname does not 5984 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 5985 returned. 5987 IMPLEMENTATION 5989 Draft Specification NFS version 4 Protocol November 2001 5991 Changes to any property of the "hard" linked files are reflected in 5992 all of the linked files. When a link is made to a file, the 5993 attributes for the file should have a value for numlinks that is 5994 one greater than the value before the LINK operation. 5996 The comments under RENAME regarding object and target residing on 5997 the same file system apply here as well. The comments regarding the 5998 target name applies as well. 6000 Note that symbolic links are created with the CREATE operation. 6002 ERRORS 6004 NFS4ERR_ACCES 6005 NFS4ERR_BADHANDLE 6006 NFS4ERR_BADXDR 6007 NFS4ERR_DELAY 6008 NFS4ERR_DQUOT 6009 NFS4ERR_EXIST 6010 NFS4ERR_FHEXPIRED 6011 NFS4ERR_INVAL 6012 NFS4ERR_IO 6013 NFS4ERR_ISDIR 6014 NFS4ERR_MLINK 6015 NFS4ERR_MOVED 6016 NFS4ERR_NAMETOOLONG 6017 NFS4ERR_NOFILEHANDLE 6018 NFS4ERR_NOSPC 6019 NFS4ERR_NOTDIR 6020 NFS4ERR_NOTSUPP 6021 NFS4ERR_RESOURCE 6022 NFS4ERR_ROFS 6023 NFS4ERR_SERVERFAULT 6024 NFS4ERR_STALE 6025 NFS4ERR_WRONGSEC 6026 NFS4ERR_XDEV 6028 Draft Specification NFS version 4 Protocol November 2001 6030 14.2.10. Operation 12: LOCK - Create Lock 6032 SYNOPSIS 6034 (cfh) type, seqid, reclaim, stateid, offset, length -> stateid, 6035 access 6037 ARGUMENT 6039 enum nfs4_lock_type { 6040 READ_LT = 1, 6041 WRITE_LT = 2, 6042 READW_LT = 3, /* blocking read */ 6043 WRITEW_LT = 4 /* blocking write */ 6044 }; 6046 struct LOCK4args { 6047 /* CURRENT_FH: file */ 6048 nfs_lock_type4 locktype; 6049 seqid4 seqid; 6050 bool reclaim; 6051 stateid4 stateid; 6052 offset4 offset; 6053 length4 length; 6054 }; 6056 RESULT 6058 struct LOCK4denied { 6059 nfs_lockowner4 owner; 6060 offset4 offset; 6061 length4 length; 6062 }; 6064 union LOCK4res switch (nfsstat4 status) { 6065 case NFS4_OK: 6066 stateid4 stateid; 6067 case NFS4ERR_DENIED: 6068 LOCK4denied denied; 6069 default: 6070 void; 6071 }; 6073 DESCRIPTION 6075 The LOCK operation requests a record lock for the byte range 6076 specified by the offset and length parameters. The lock type is 6077 also specified to be one of the nfs4_lock_types. If this is a 6079 Draft Specification NFS version 4 Protocol November 2001 6081 reclaim request, the reclaim parameter will be TRUE; 6083 Bytes in a file may be locked even if those bytes are not currently 6084 allocated to the file. To lock the file from a specific offset 6085 through the end-of-file (no matter how long the file actually is) 6086 use a length field with all bits set to 1 (one). To lock the 6087 entire file, use an offset of 0 (zero) and a length with all bits 6088 set to 1. A length of 0 is reserved and should not be used. 6090 In the case that the lock is denied, the owner, offset, and length 6091 of a conflicting lock are returned. 6093 On success, the current filehandle retains its value. 6095 IMPLEMENTATION 6097 If the server is unable to determine the exact offset and length of 6098 the conflicting lock, the same offset and length that were provided 6099 in the arguments should be returned in the denied results. The 6100 File Locking section contains a full description of this and the 6101 other file locking operations. 6103 ERRORS 6105 NFS4ERR_ACCES 6106 NFS4ERR_BADHANDLE 6107 NFS4ERR_BAD_SEQID 6108 NFS4ERR_BAD_STATEID 6109 NFS4ERR_BADXDR 6110 NFS4ERR_DELAY 6111 NFS4ERR_DENIED 6112 NFS4ERR_EXPIRED 6113 NFS4ERR_FHEXPIRED 6114 NFS4ERR_GRACE 6115 NFS4ERR_INVAL 6116 NFS4ERR_ISDIR 6117 NFS4ERR_LEASE_MOVED 6118 NFS4ERR_LOCK_RANGE 6119 NFS4ERR_MOVED 6120 NFS4ERR_NOFILEHANDLE 6121 NFS4ERR_NO_GRACE 6122 NFS4ERR_OLD_STATEID 6123 NFS4ERR_RECLAIM_BAD 6124 NFS4ERR_RECLAIM_CONFLICT 6125 NFS4ERR_RESOURCE 6126 NFS4ERR_SERVERFAULT 6127 NFS4ERR_STALE 6128 NFS4ERR_STALE_CLIENTID 6129 NFS4ERR_STALE_STATEID 6130 NFS4ERR_WRONGSEC 6132 Draft Specification NFS version 4 Protocol November 2001 6134 14.2.11. Operation 13: LOCKT - Test For Lock 6136 SYNOPSIS 6138 (cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED -> 6139 owner} 6141 ARGUMENT 6143 struct LOCKT4args { 6144 /* CURRENT_FH: file */ 6145 nfs_lock_type4 locktype; 6146 nfs_lockowner4 owner; 6147 offset4 offset; 6148 length4 length; 6149 }; 6151 RESULT 6153 struct LOCK4denied { 6154 nfs_lockowner4 owner; 6155 offset4 offset; 6156 length4 length; 6157 nfs_lock_type4 locktype; 6158 }; 6160 union LOCKT4res switch (nfsstat4 status) { 6161 case NFS4ERR_DENIED: 6162 LOCK4denied denied; 6163 case NFS4_OK: 6164 void; 6165 default: 6166 void; 6167 }; 6169 DESCRIPTION 6171 The LOCKT operation tests the lock as specified in the arguments. 6172 If a conflicting lock exists, the owner, offset, length, and type 6173 of the conflicting lock are returned; if no lock is held, nothing 6174 other than NFS4_OK is returned. 6176 On success, the current filehandle retains its value. 6178 IMPLEMENTATION 6180 If the server is unable to determine the exact offset and length of 6182 Draft Specification NFS version 4 Protocol November 2001 6184 the conflicting lock, the same offset and length that were provided 6185 in the arguments should be returned in the denied results. The 6186 File Locking section contains further discussion of the file 6187 locking mechanisms. 6189 LOCKT uses nfs_lockowner4 instead of a stateid4, as LOCK does, to 6190 identify the owner so that the client does not have to open the 6191 file to test for the existence of a lock. 6193 ERRORS 6195 NFS4ERR_ACCES 6196 NFS4ERR_BADHANDLE 6197 NFS4ERR_BADXDR 6198 NFS4ERR_DELAY 6199 NFS4ERR_DENIED 6200 NFS4ERR_FHEXPIRED 6201 NFS4ERR_GRACE 6202 NFS4ERR_INVAL 6203 NFS4ERR_ISDIR 6204 NFS4ERR_LEASE_MOVED 6205 NFS4ERR_LOCK_RANGE 6206 NFS4ERR_MOVED 6207 NFS4ERR_NOFILEHANDLE 6208 NFS4ERR_RESOURCE 6209 NFS4ERR_SERVERFAULT 6210 NFS4ERR_STALE 6211 NFS4ERR_STALE_CLIENTID 6212 NFS4ERR_WRONGSEC 6214 Draft Specification NFS version 4 Protocol November 2001 6216 14.2.12. Operation 14: LOCKU - Unlock File 6218 SYNOPSIS 6220 (cfh) type, seqid, stateid, offset, length -> stateid 6222 ARGUMENT 6224 struct LOCKU4args { 6225 /* CURRENT_FH: file */ 6226 nfs_lock_type4 locktype; 6227 seqid4 seqid; 6228 stateid4 stateid; 6229 offset4 offset; 6230 length4 length; 6231 }; 6233 RESULT 6235 union LOCKU4res switch (nfsstat4 status) { 6236 case NFS4_OK: 6237 stateid4 stateid; 6238 default: 6239 void; 6240 }; 6242 DESCRIPTION 6244 The LOCKU operation unlocks the record lock specified by the 6245 parameters. 6247 On success, the current filehandle retains its value. 6249 IMPLEMENTATION 6251 The File Locking section contains a full description of this and 6252 the other file locking procedures. 6254 ERRORS 6256 NFS4ERR_ACCES 6257 NFS4ERR_BADHANDLE 6258 NFS4ERR_BAD_SEQID 6259 NFS4ERR_BAD_STATEID 6260 NFS4ERR_BADXDR 6261 NFS4ERR_EXPIRED 6262 NFS4ERR_FHEXPIRED 6264 Draft Specification NFS version 4 Protocol November 2001 6266 NFS4ERR_GRACE 6267 NFS4ERR_INVAL 6268 NFS4ERR_LOCK_RANGE 6269 NFS4ERR_LEASE_MOVED 6270 NFS4ERR_MOVED 6271 NFS4ERR_NOFILEHANDLE 6272 NFS4ERR_OLD_STATEID 6273 NFS4ERR_RESOURCE 6274 NFS4ERR_SERVERFAULT 6275 NFS4ERR_STALE 6276 NFS4ERR_STALE_CLIENTID 6277 NFS4ERR_STALE_STATEID 6279 Draft Specification NFS version 4 Protocol November 2001 6281 14.2.13. Operation 15: LOOKUP - Lookup Filename 6283 SYNOPSIS 6285 (cfh), component -> (cfh) 6287 ARGUMENT 6289 struct LOOKUP4args { 6290 /* CURRENT_FH: directory */ 6291 component4 objname; 6292 }; 6294 RESULT 6296 struct LOOKUP4res { 6297 /* CURRENT_FH: object */ 6298 nfsstat4 status; 6299 }; 6301 DESCRIPTION 6303 This operation LOOKUPs or finds a file system object using the 6304 directory specified by the current filehandle. LOOKUP evaluates 6305 the component and if the object exists the current filehandle is 6306 replaced with the component's filehandle. 6308 If the component cannot be evaluated either because it does not 6309 exist or because the client does not have permission to evaluate 6310 the component, then an error will be returned and the current 6311 filehandle will be unchanged. 6313 If the component is a zero length string or if any component does 6314 not obey the UTF-8 definition, the error NFS4ERR_INVAL will be 6315 returned. 6317 IMPLEMENTATION 6319 If the client wants to acheive the effect of a multi-component 6320 lookup, it may construct a COMPOUND request such as (and obtain 6321 each filehandle): 6323 Draft Specification NFS version 4 Protocol November 2001 6325 PUTFH (directory filehandle) 6326 LOOKUP "pub" 6327 GETFH 6328 LOOKUP "foo" 6329 GETFH 6330 LOOKUP "bar" 6331 GETFH 6333 NFS version 4 servers depart from the semantics of previous NFS 6334 versions in allowing LOOKUP requests to cross mountpoints on the 6335 server. The client can detect a mountpoint crossing by comparing 6336 the fsid attribute of the directory with the fsid attribute of the 6337 directory looked up. If the fsids are different then the new 6338 directory is a server mountpoint. Unix clients that detect a 6339 mountpoint crossing will need to mount the server's filesystem. 6340 This needs to be done to maintain the file object identity checking 6341 mechanisms common to Unix clients. 6343 Servers that limit NFS access to "shares" or "exported" filesystems 6344 should provide a pseudo-filesystem into which the exported 6345 filesystems can be integrated, so that clients can browse the 6346 server's name space. The clients view of a pseudo filesystem will 6347 be limited to paths that lead to exported filesystems. 6349 Note: previous versions of the protocol assigned special semantics 6350 to the names "." and "..". NFS version 4 assigns no special 6351 semantics to these names. The LOOKUPP operator must be used to 6352 lookup a parent directory. 6354 Note that this procedure does not follow symbolic links. The 6355 client is responsible for all parsing of filenames including 6356 filenames that are modified by symbolic links encountered during 6357 the lookup process. 6359 If the current file handle supplied is not a directory but a 6360 symbolic link, the error NFS4ERR_SYMLINK is returned as the error. 6361 For all other non-directory file types, the error NFS4ERR_NOTDIR is 6362 returned. 6364 ERRORS 6366 NFS4ERR_ACCES 6367 NFS4ERR_BADHANDLE 6368 NFS4ERR_BADXDR 6369 NFS4ERR_FHEXPIRED 6370 NFS4ERR_INVAL 6371 NFS4ERR_IO 6372 NFS4ERR_MOVED 6373 NFS4ERR_NAMETOOLONG 6374 NFS4ERR_NOENT 6376 Draft Specification NFS version 4 Protocol November 2001 6378 NFS4ERR_NOFILEHANDLE 6379 NFS4ERR_NOTDIR 6380 NFS4ERR_RESOURCE 6381 NFS4ERR_SERVERFAULT 6382 NFS4ERR_STALE 6383 NFS4ERR_SYMLINK 6384 NFS4ERR_WRONGSEC 6386 Draft Specification NFS version 4 Protocol November 2001 6388 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory 6390 SYNOPSIS 6392 (cfh) -> (cfh) 6394 ARGUMENT 6396 /* CURRENT_FH: object */ 6397 void; 6399 RESULT 6401 struct LOOKUPP4res { 6402 /* CURRENT_FH: directory */ 6403 nfsstat4 status; 6404 }; 6406 DESCRIPTION 6408 The current filehandle is assumed to refer to a regular directory 6409 or a named attribute directory. LOOKUPP assigns the filehandle for 6410 its parent directory to be the current filehandle. If there is no 6411 parent directory an NFS4ERR_ENOENT error must be returned. 6412 Therefore, NFS4ERR_ENOENT will be returned by the server when the 6413 current filehandle is at the root or top of the server's file tree. 6415 IMPLEMENTATION 6417 As for LOOKUP, LOOKUPP will also cross mountpoints. 6419 If the current filehandle is not a directory or named attribute 6420 directory, the error NFS4ERR_NOTDIR is returned. 6422 ERRORS 6424 NFS4ERR_ACCES 6425 NFS4ERR_BADHANDLE 6426 NFS4ERR_FHEXPIRED 6427 NFS4ERR_INVAL 6428 NFS4ERR_IO 6429 NFS4ERR_MOVED 6430 NFS4ERR_NOENT 6431 NFS4ERR_NOFILEHANDLE 6432 NFS4ERR_NOTDIR 6433 NFS4ERR_RESOURCE 6434 NFS4ERR_SERVERFAULT 6435 NFS4ERR_STALE 6437 Draft Specification NFS version 4 Protocol November 2001 6439 NFS4ERR_WRONGSEC 6441 Draft Specification NFS version 4 Protocol November 2001 6443 14.2.15. Operation 17: NVERIFY - Verify Difference in Attributes 6445 SYNOPSIS 6447 (cfh), fattr -> - 6449 ARGUMENT 6451 struct NVERIFY4args { 6452 /* CURRENT_FH: object */ 6453 fattr4 obj_attributes; 6454 }; 6456 RESULT 6458 struct NVERIFY4res { 6459 nfsstat4 status; 6460 }; 6462 DESCRIPTION 6464 This operation is used to prefix a sequence of operations to be 6465 performed if one or more attributes have changed on some filesystem 6466 object. If all the attributes match then the error NFS4ERR_SAME 6467 must be returned. 6469 On success, the current filehandle retains its value. 6471 IMPLEMENTATION 6473 This operation is useful as a cache validation operator. If the 6474 object to which the attributes belong has changed then the 6475 following operations may obtain new data associated with that 6476 object. For instance, to check if a file has been changed and 6477 obtain new data if it has: 6479 PUTFH (public) 6480 LOOKUP "pub" "foo" "bar" 6481 NVERIFY attrbits attrs 6482 READ 0 32767 6484 In the case that a recommended attribute is specified in the 6485 NVERIFY operation and the server does not support that attribute 6486 for the file system object, the error NFS4ERR_NOTSUPP is returned 6487 to the client. 6489 Draft Specification NFS version 4 Protocol November 2001 6491 ERRORS 6493 NFS4ERR_ACCES 6494 NFS4ERR_ATTRNOTSUPP 6495 NFS4ERR_BADHANDLE 6496 NFS4ERR_BADXDR 6497 NFS4ERR_DELAY 6498 NFS4ERR_FHEXPIRED 6499 NFS4ERR_INVAL 6500 NFS4ERR_IO 6501 NFS4ERR_MOVED 6502 NFS4ERR_NOFILEHANDLE 6503 NFS4ERR_NOTSUPP 6504 NFS4ERR_RESOURCE 6505 NFS4ERR_SAME 6506 NFS4ERR_SERVERFAULT 6507 NFS4ERR_STALE 6508 NFS4ERR_WRONGSEC 6510 Draft Specification NFS version 4 Protocol November 2001 6512 14.2.16. Operation 18: OPEN - Open a Regular File 6514 SYNOPSIS 6516 (cfh), claim, openhow, owner, seqid, access, deny -> (cfh), 6517 stateid, cinfo, rflags, open_confirm, attrset delegation 6519 ARGUMENT 6521 struct OPEN4args { 6522 open_claim4 claim; 6523 openflag4 openhow; 6524 nfs_lockowner4 owner; 6525 seqid4 seqid; 6526 uint32_t share_access; 6527 uint32_t share_deny; 6528 }; 6530 enum createmode4 { 6531 UNCHECKED4 = 0, 6532 GUARDED4 = 1, 6533 EXCLUSIVE4 = 2 6534 }; 6536 union createhow4 switch (createmode4 mode) { 6537 case UNCHECKED4: 6538 case GUARDED4: 6539 fattr4 createattrs; 6540 case EXCLUSIVE4: 6541 verifier4 createverf; 6542 }; 6544 enum opentype4 { 6545 OPEN4_NOCREATE = 0, 6546 OPEN4_CREATE = 1 6547 }; 6549 union openflag4 switch (opentype4 opentype) { 6550 case OPEN4_CREATE: 6551 createhow4 how; 6552 default: 6553 void; 6554 }; 6556 /* Next definitions used for OPEN delegation */ 6557 enum limit_by4 { 6558 NFS_LIMIT_SIZE = 1, 6559 NFS_LIMIT_BLOCKS = 2 6560 /* others as needed */ 6561 }; 6563 Draft Specification NFS version 4 Protocol November 2001 6565 struct nfs_modified_limit4 { 6566 uint32_t num_blocks; 6567 uint32_t bytes_per_block; 6568 }; 6570 union nfs_space_limit4 switch (limit_by4 limitby) { 6571 /* limit specified as file size */ 6572 case NFS_LIMIT_SIZE: 6573 uint64_t filesize; 6574 /* limit specified by number of blocks */ 6575 case NFS_LIMIT_BLOCKS: 6576 nfs_modified_limit4 mod_blocks; 6577 } ; 6579 enum open_delegation_type4 { 6580 OPEN_DELEGATE_NONE = 0, 6581 OPEN_DELEGATE_READ = 1, 6582 OPEN_DELEGATE_WRITE = 2 6583 }; 6585 enum open_claim_type4 { 6586 CLAIM_NULL = 0, 6587 CLAIM_PREVIOUS = 1, 6588 CLAIM_DELEGATE_CUR = 2, 6589 CLAIM_DELEGATE_PREV = 3 6590 }; 6592 struct open_claim_delegate_cur4 { 6593 stateid4 delegate_stateid; 6594 component4 file; 6595 }; 6597 union open_claim4 switch (open_claim_type4 claim) { 6598 /* 6599 * No special rights to file. Ordinary OPEN of the specified file. 6600 */ 6601 case CLAIM_NULL: 6602 /* CURRENT_FH: directory */ 6603 component4 file; 6605 /* 6606 * Right to the file established by an open previous to server 6607 * reboot. File identified by filehandle obtained at that time 6608 * rather than by name. 6609 */ 6610 case CLAIM_PREVIOUS: 6611 /* CURRENT_FH: file being reclaimed */ 6612 open_delegation_type4 delegate_type; 6614 /* 6615 * Right to file based on a delegation granted by the server. 6616 * File is specified by name. 6618 Draft Specification NFS version 4 Protocol November 2001 6620 */ 6621 case CLAIM_DELEGATE_CUR: 6622 /* CURRENT_FH: directory */ 6623 open_claim_delegate_cur4 delegate_cur_info; 6625 /* Right to file based on a delegation granted to a previous boot 6626 * instance of the client. File is specified by name. 6627 */ 6628 case CLAIM_DELEGATE_PREV: 6629 /* CURRENT_FH: directory */ 6630 component4 file_delegate_prev; 6631 }; 6633 RESULT 6635 struct open_read_delegation4 { 6636 stateid4 stateid; /* Stateid for delegation*/ 6637 bool recall; /* Pre-recalled flag for 6638 delegations obtained 6639 by reclaim 6640 (CLAIM_PREVIOUS) */ 6641 nfsace4 permissions; /* Defines users who don't 6642 need an ACCESS call to 6643 open for read */ 6644 }; 6646 struct open_write_delegation4 { 6647 stateid4 stateid; /* Stateid for delegation*/ 6648 bool recall; /* Pre-recalled flag for 6649 delegations obtained 6650 by reclaim 6651 (CLAIM_PREVIOUS) */ 6652 nfs_space_limit4 space_limit; /* Defines condition that 6653 the client must check to 6654 determine whether the 6655 file needs to be flushed 6656 to the server on close. 6657 */ 6658 nfsace4 permissions; /* Defines users who don't 6659 need an ACCESS call as 6660 part of a delegated 6661 open. */ 6662 }; 6664 union open_delegation4 6665 switch (open_delegation_type4 delegation_type) { 6666 case OPEN_DELEGATE_NONE: 6667 void; 6668 case OPEN_DELEGATE_READ: 6669 open_read_delegation4 read; 6671 Draft Specification NFS version 4 Protocol November 2001 6673 case OPEN_DELEGATE_WRITE: 6674 open_write_delegation4 write; 6675 }; 6677 const OPEN4_RESULT_MLOCK = 0x00000001; 6678 const OPEN4_RESULT_CONFIRM= 0x00000002; 6680 struct OPEN4resok { 6681 stateid4 stateid; /* Stateid for open */ 6682 change_info4 cinfo; /* Directory Change Info */ 6683 uint32_t rflags; /* Result flags */ 6684 bitmap4 attrset; /* attributes on create */ 6685 open_delegation4 delegation; /* Info on any open 6686 delegation */ 6687 }; 6689 union OPEN4res switch (nfsstat4 status) { 6690 case NFS4_OK: 6691 /* CURRENT_FH: opened file */ 6692 OPEN4resok resok4; 6693 default: 6694 void; 6695 }; 6697 WARNING TO CLIENT IMPLEMENTORS 6699 OPEN resembles LOOKUP in that it generates a filehandle for the 6700 client to use. Unlike LOOKUP though, OPEN creates server state on 6701 the filehandle. In normal circumstances, the client can only 6702 release this state with a CLOSE operation. CLOSE uses the current 6703 filehandle to determine which file to close. Therefore the client 6704 MUST follow every OPEN operation with a GETFH operation in the same 6705 COMPOUND procedure. This will supply the client with the 6706 filehandle such that CLOSE can be used appropriately. 6708 Simply waiting for the lease on the file to expire is insufficient 6709 because the server may maintain the state indefinitely as long as 6710 another client does not attempt to make a conflicting access to the 6711 same file. 6713 DESCRIPTION 6715 The OPEN operation creates and/or opens a regular file in a 6716 directory with the provided name. If the file does not exist at 6717 the server and creation is desired, specification of the method of 6718 creation is provided by the openhow parameter. The client has the 6719 choice of three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE. 6721 UNCHECKED means that the file should be created if a file of that 6722 name does not exist and encountering an existing regular file of 6724 Draft Specification NFS version 4 Protocol November 2001 6726 that name is not an error. For this type of create, createattrs 6727 specifies the initial set of attributes for the file. The set of 6728 attributes may include any writable attribute valid for regular 6729 files. When an UNCHECKED create encounters an existing file, the 6730 attributes specified by createattrs is not used, except that when 6731 an object_size of zero is specified, the existing file is 6732 truncated. If GUARDED is specified, the server checks for the 6733 presence of a duplicate object by name before performing the 6734 create. If a duplicate exists, an error of NFS4ERR_EXIST is 6735 returned as the status. If the object does not exist, the request 6736 is performed as described for UNCHECKED. For each of these cases 6737 (UNCHECKED and GUARDED) where the operation is successful, the 6738 server will return to the client an attribute mask signifying which 6739 attributes were successfully set for the object. 6741 EXCLUSIVE specifies that the server is to follow exclusive creation 6742 semantics, using the verifier to ensure exclusive creation of the 6743 target. The server should check for the presence of a duplicate 6744 object by name. If the object does not exist, the server creates 6745 the object and stores the verifier with the object. If the object 6746 does exist and the stored verifier matches the client provided 6747 verifier, the server uses the existing object as the newly created 6748 object. If the stored verifier does not match, then an error of 6749 NFS4ERR_EXIST is returned. No attributes may be provided in this 6750 case, since the server may use an attribute of the target object to 6751 store the verifier. If the server uses an attribute to store the 6752 exclusive create verifier, it will signify which attribute by 6753 setting the appropriate bit in the attribute mask that is returned 6754 in the results. 6756 For the target directory, the server returns change_info4 6757 information in cinfo. With the atomic field of the change_info4 6758 struct, the server will indicate if the before and after change 6759 attributes were obtained atomically with respect to the link 6760 creation. 6762 Upon successful creation, the current filehandle is replaced by 6763 that of the new object. 6765 The OPEN procedure provides for DOS SHARE capability with the use 6766 of the access and deny fields of the OPEN arguments. The client 6767 specifies at OPEN the required access and deny modes. For clients 6768 that do not directly support SHAREs (i.e. Unix), the expected deny 6769 value is DENY_NONE. In the case that there is a existing SHARE 6770 reservation that conflicts with the OPEN request, the server 6771 returns the error NFS4ERR_DENIED. For a complete SHARE request, 6772 the client must provide values for the owner and seqid fields for 6773 the OPEN argument. For additional discussion of SHARE semantics 6774 see the section on 'Share Reservations'. 6776 In the case that the client is recovering state from a server 6777 failure, the reclaim field of the OPEN argument is used to signify 6779 Draft Specification NFS version 4 Protocol November 2001 6781 that the request is meant to reclaim state previously held. 6783 The "claim" field of the OPEN argument is used to specify the file 6784 to be opened and the state information which the client claims to 6785 possess. There are four basic claim types which cover the various 6786 situations for an OPEN. They are as follows: 6788 CLAIM_NULL For the client, this is a new OPEN 6789 request and there is no previous state 6790 associate with the file for the client. 6792 CLAIM_PREVIOUS The client is claiming basic OPEN state 6793 for a file that was held previous to a 6794 server reboot. Generally used when a 6795 server is returning persistent file 6796 handles; the client may not have the 6797 file name to reclaim the OPEN. 6799 CLAIM_DELEGATE_CUR The client is claiming a delegation for 6800 OPEN as granted by the server. 6801 Generally this is done as part of 6802 recalling a delegation. 6804 CLAIM_DELEGATE_PREV The client is claiming a delegation 6805 granted to a previous client instance; 6806 used after the client reboots. 6808 For OPEN requests whose claim type is other than CLAIM_PREVIOUS 6809 (i.e. requests other than those devoted to reclaiming opens after a 6810 server reboot) that reach the server during its grace or lease 6811 expiration period, the server returns an error of NFS4ERR_GRACE. 6813 For any OPEN request, the server may return an open delegation, 6814 which allows further opens and closes to be handled locally on the 6815 client as described in the section Open Delegation. Note that 6816 delegation is up to the server to decide. The client should never 6817 assume that delegation will or will not be granted in a particular 6818 instance. It should always be prepared for either case. A partial 6819 exception is the reclaim (CLAIM_PREVIOUS) case, in which a 6820 delegation type is claimed. In this case, delegation will always 6821 be granted, although the server may specify an immediate recall in 6822 the delegation structure. 6824 The rflags returned by a successful OPEN allow the server to return 6825 information governing how the open file is to be handled. 6826 OPEN4_RESULT_MLOCK indicates to the caller that mandatory locking 6827 is in effect for this file and the client should act appropriately 6828 with regard to data cached on the client. OPEN4_RESULT_CONFIRM 6829 indicates that the client MUST execute an OPEN_CONFIRM operation 6830 before using the open file. 6832 Draft Specification NFS version 4 Protocol November 2001 6834 If the component is of zero length or if the component does not 6835 obey the UTF-8 definition, the error NFS4ERR_INVAL will be 6836 returned. 6838 When an OPEN is done and the specified lockowner already has the 6839 resulting filehandle open, the result is to "OR" together the new 6840 share and deny status together with the existing status. In this 6841 case, only a single CLOSE need be done, even though multiple OPEN's 6842 were completed. 6844 IMPLEMENTATION 6846 The OPEN procedure contains support for EXCLUSIVE create. The 6847 mechanism is similar to the support in NFS version 3 [RFC1813]. As 6848 in NFS version 3, this mechanism provides reliable exclusive 6849 creation. Exclusive create is invoked when the how parameter is 6850 EXCLUSIVE. In this case, the client provides a verifier that can 6851 reasonably be expected to be unique. A combination of a client 6852 identifier, perhaps the client network address, and a unique number 6853 generated by the client, perhaps the RPC transaction identifier, 6854 may be appropriate. 6856 If the object does not exist, the server creates the object and 6857 stores the verifier in stable storage. For file systems that do not 6858 provide a mechanism for the storage of arbitrary file attributes, 6859 the server may use one or more elements of the object meta-data to 6860 store the verifier. The verifier must be stored in stable storage 6861 to prevent erroneous failure on retransmission of the request. It 6862 is assumed that an exclusive create is being performed because 6863 exclusive semantics are critical to the application. Because of the 6864 expected usage, exclusive CREATE does not rely solely on the 6865 normally volatile duplicate request cache for storage of the 6866 verifier. The duplicate request cache in volatile storage does not 6867 survive a crash and may actually flush on a long network partition, 6868 opening failure windows. In the UNIX local file system 6869 environment, the expected storage location for the verifier on 6870 creation is the meta-data (time stamps) of the object. For this 6871 reason, an exclusive object create may not include initial 6872 attributes because the server would have nowhere to store the 6873 verifier. 6875 If the server can not support these exclusive create semantics, 6876 possibly because of the requirement to commit the verifier to 6877 stable storage, it should fail the OPEN request with the error, 6878 NFS4ERR_NOTSUPP. 6880 During an exclusive CREATE request, if the object already exists, 6881 the server reconstructs the object's verifier and compares it with 6882 the verifier in the request. If they match, the server treats the 6883 request as a success. The request is presumed to be a duplicate of 6884 an earlier, successful request for which the reply was lost and 6886 Draft Specification NFS version 4 Protocol November 2001 6888 that the server duplicate request cache mechanism did not detect. 6889 If the verifiers do not match, the request is rejected with the 6890 status, NFS4ERR_EXIST. 6892 Once the client has performed a successful exclusive create, it 6893 must issue a SETATTR to set the correct object attributes. Until 6894 it does so, it should not rely upon any of the object attributes, 6895 since the server implementation may need to overload object meta- 6896 data to store the verifier. The subsequent SETATTR must not occur 6897 in the same COMPOUND request as the OPEN. This separation will 6898 guarantee that the exclusive create mechanism will continue to 6899 function properly in the face of retransmission of the request. 6901 Use of the GUARDED attribute does not provide exactly-once 6902 semantics. In particular, if a reply is lost and the server does 6903 not detect the retransmission of the request, the procedure can 6904 fail with NFS4ERR_EXIST, even though the create was performed 6905 successfully. 6907 For SHARE reservations, the client must specify a value for access 6908 that is one of READ, WRITE, or BOTH. For deny, the client must 6909 specify one of NONE, READ, WRITE, or BOTH. If the client fails to 6910 do this, the server must return NFS4ERR_INVAL. 6912 If the component provided to OPEN is a symbolic link, the error 6913 NFS4ERR_SYMLINK will be returned to the client. If the current 6914 filehandle is not a directory, the error NFS4ERR_NOTDIR will be 6915 returned. 6917 ERRORS 6919 NFS4ERR_ACCES 6920 NFS4ERR_ATTRNOTSUPP 6921 NFS4ERR_BAD_SEQID 6922 NFS4ERR_BADXDR 6923 NFS4ERR_DELAY 6924 NFS4ERR_DQUOT 6925 NFS4ERR_EXIST 6926 NFS4ERR_FHEXPIRED 6927 NFS4ERR_GRACE 6928 NFS4ERR_IO 6929 NFS4ERR_ISDIR 6930 NFS4ERR_LEASE_MOVED 6931 NFS4ERR_MOVED 6932 NFS4ERR_NAMETOOLONG 6933 NFS4ERR_NOENT 6934 NFS4ERR_NOFILEHANDLE 6935 NFS4ERR_NO_GRACE 6936 NFS4ERR_NOSPC 6937 NFS4ERR_NOTDIR 6938 NFS4ERR_NOTSUPP 6940 Draft Specification NFS version 4 Protocol November 2001 6942 NFS4ERR_RECLAIM_BAD 6943 NFS4ERR_RECLAIM_CONFLICT 6944 NFS4ERR_RESOURCE 6945 NFS4ERR_ROFS 6946 NFS4ERR_SERVERFAULT 6947 NFS4ERR_SHARE_DENIED 6948 NFS4ERR_STALE_CLIENTID 6949 NFS4ERR_SYMLINK 6951 Draft Specification NFS version 4 Protocol November 2001 6953 14.2.17. Operation 19: OPENATTR - Open Named Attribute Directory 6955 SYNOPSIS 6957 (cfh) createdir -> (cfh) 6959 ARGUMENT 6961 struct OPENATTR4args { 6962 /* CURRENT_FH: object */ 6963 bool createdir; 6964 }; 6966 RESULT 6968 struct OPENATTR4res { 6969 /* CURRENT_FH: named attr directory*/ 6970 nfsstat4 status; 6971 }; 6973 DESCRIPTION 6975 The OPENATTR operation is used to obtain the filehandle of the 6976 named attribute directory associated with the current filehandle. 6977 The result of the OPENATTR will be a filehandle to an object of 6978 type NF4ATTRDIR. From this filehandle, READDIR and LOOKUP 6979 procedures can be used to obtain filehandles for the various named 6980 attributes associated with the original file system object. 6981 Filehandles returned within the named attribute directory will have 6982 a type of NF4NAMEDATTR. 6984 The createdir argument allows the client to signify if a named 6985 attribute directory should be created as a result of the OPENATTR 6986 operation. Some clients may use the OPENATTR operation with a 6987 value of FALSE for createdir to determine if any named attributes 6988 exist for the object. If none exist, then NFS4ERR_NOENT will be 6989 returned. If createdir has a value of TRUE and no named attribute 6990 directory exists, one is created. The creation of a named 6991 attribute directory assumes that the server has implemented named 6992 attribute support in this fashion and is not required to do so by 6993 this definition. 6995 IMPLEMENTATION 6997 If the server does not support named attributes for the current 6998 filehandle, an error of NFS4ERR_NOTSUPP will be returned to the 6999 client. 7001 Draft Specification NFS version 4 Protocol November 2001 7003 ERRORS 7005 NFS4ERR_ACCES 7006 NFS4ERR_BADHANDLE 7007 NFS4ERR_BADXDR 7008 NFS4ERR_DELAY 7009 NFS4ERR_EROFS 7010 NFS4ERR_FHEXPIRED 7011 NFS4ERR_INVAL 7012 NFS4ERR_IO 7013 NFS4ERR_MOVED 7014 NFS4ERR_NOENT 7015 NFS4ERR_NOFILEHANDLE 7016 NFS4ERR_NOTSUPP 7017 NFS4ERR_RESOURCE 7018 NFS4ERR_SERVERFAULT 7019 NFS4ERR_STALE 7020 NFS4ERR_WRONGSEC 7022 Draft Specification NFS version 4 Protocol November 2001 7024 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open 7026 SYNOPSIS 7028 (cfh), seqid, stateid-> stateid 7030 ARGUMENT 7032 struct OPEN_CONFIRM4args { 7033 /* CURRENT_FH: opened file */ 7034 seqid4 seqid; 7035 stateid4 stateid; 7036 }; 7038 RESULT 7040 struct OPEN_CONFIRM4resok { 7041 stateid4 stateid; 7042 }; 7044 union OPEN_CONFIRM4res switch (nfsstat4 status) { 7045 case NFS4_OK: 7046 OPEN_CONFIRM4resok resok4; 7047 default: 7048 void; 7049 }; 7051 DESCRIPTION 7053 This operation is used to confirm the sequence id usage for the 7054 first time that a nfs_lockowner is used by a client. The stateid 7055 returned from the OPEN operation is used as the argument for this 7056 operation along with the next sequence id for the nfs_lockowner. 7057 The sequence id passed to the OPEN_CONFIRM must be 1 (one) greater 7058 than the seqid passed to the OPEN operation from which the 7059 open_confirm value was obtained. If the server receives an 7060 unexpected sequence id with respect to the original open, then the 7061 server assumes that the client will not confirm the original OPEN 7062 and all state associated with the original OPEN is released by the 7063 server. 7065 On success, the current filehandle retains its value. 7067 IMPLEMENTATION 7069 A given client might generate many nfs_lockowner data structures 7070 for a given clientid. The client will periodically either dispose 7071 of its nfs_lockowners or stop using them for indefinite periods of 7073 Draft Specification NFS version 4 Protocol November 2001 7075 time. The latter situation is why the NFS version 4 protocol does 7076 not have a an explicit operation to exit an nfs_lockowner: such an 7077 operation is of no use in that situation. Instead, to avoid 7078 unbounded memory use, the server needs to implement a strategy for 7079 disposing of nfs_lockowners that have no current lock, open, or 7080 delegation state for any files and have not been used recently. 7081 The time period used to determine when to dispose of nfs_lockowners 7082 is an implementation choice. The time period should certainly be 7083 no less than the lease time plus any grace period the server wishes 7084 to implement beyond a lease time. The OPEN_CONFIRM operation 7085 allows the server to safely dispose of unused nfs_lockowner data 7086 structures. 7088 In the case that a client issues an OPEN operation and the server 7089 no longer has a record of the nfs_lockowner, the server needs 7090 ensure that this is a new OPEN and not a replay or retransmission. 7092 A lazy server implementation might require confirmation for every 7093 nfs_lockowner for which it has no record. However, this is not 7094 necessary until the server records the fact that it has disposed of 7095 one nfs_lockowner for the given clientid. 7097 The server must hold unconfirmed OPEN state until one of three 7098 events occur. First, the client sends an OPEN_CONFIRM request with 7099 the appropriate sequence id and stateid within the lease period. 7100 In this case, the OPEN state on the server goes to confirmed, and 7101 the nfs_lockowner on the server is fully established. 7103 Second, the client sends another OPEN request with a sequence id 7104 that is incorrect for the nfs_lockowner (out of sequence). In this 7105 case, the server assumes the second OPEN request is valid and the 7106 first one is a replay. The server cancels the OPEN state of the 7107 first OPEN request, establishes an unconfirmed OPEN state for the 7108 second OPEN request, and responds to the second OPEN request with 7109 an indication that an OPEN_CONFIRM is needed. The process then 7110 repeats itself. While there is a potential for a denial of service 7111 attack on the client, it is mitigated if the client and server 7112 require the use of a security flavor based on Kerberos V5, LIPKEY, 7113 or some other flavor that uses cryptography. 7115 What if the server is in the unconfirmed OPEN state for a given 7116 nfs_lockowner, and it receives an operation on the nfs_lockowner 7117 that has a stateid but the operation is not OPEN, or it is 7118 OPEN_CONFIRM but with the wrong stateid? Then, even if the seqid 7119 is correct, the server returns NFS4ERR_BAD_STATEID, because the 7120 server assumes the operation is a replay: if the server has no 7121 established OPEN state, then there is no way, for example, a LOCK 7122 operation could be valid. 7124 Third, neither of the two aforementioned events occur for the 7125 nfs_lockowner within the lease period. In this case, the OPEN 7126 state is cancelled and disposal of the nfs_lockowner can occur. 7128 Draft Specification NFS version 4 Protocol November 2001 7130 ERRORS 7132 NFS4ERR_BADHANDLE 7133 NFS4ERR_BAD_SEQID 7134 NFS4ERR_BADXDR 7135 NFS4ERR_EXPIRED 7136 NFS4ERR_FHEXPIRED 7137 NFS4ERR_GRACE 7138 NFS4ERR_INVAL 7139 NFS4ERR_ISDIR 7140 NFS4ERR_MOVED 7141 NFS4ERR_NOENT 7142 NFS4ERR_NOFILEHANDLE 7143 NFS4ERR_NOTSUPP 7144 NFS4ERR_RESOURCE 7145 NFS4ERR_SERVERFAULT 7146 NFS4ERR_STALE 7147 NFS4ERR_WRONGSEC 7149 Draft Specification NFS version 4 Protocol November 2001 7151 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access 7153 SYNOPSIS 7155 (cfh), stateid, seqid, access, deny -> stateid 7157 ARGUMENT 7159 struct OPEN_DOWNGRADE4args { 7160 /* CURRENT_FH: opened file */ 7161 stateid4 stateid; 7162 seqid4 seqid; 7163 uint32_t share_access; 7164 uint32_t share_deny; 7165 }; 7167 RESULT 7169 struct OPEN_DOWNGRADE4resok { 7170 stateid4 stateid; 7171 }; 7173 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 7174 case NFS4_OK: 7175 OPEN_DOWNGRADE4resok resok4; 7176 default: 7177 void; 7178 }; 7180 This operation is used to adjust the access and deny bits for a given 7181 open. This is necessary when a given lockowner opens the same file 7182 multiple times with different access and deny flags. In this 7183 situation, a close of one of the open's may change the appropriate 7184 access and deny flags to remove bits associated with open's no longer 7185 in effect. 7187 The access and deny bits specified in this operation replace the 7188 current ones for the specified open file. If either the access or 7189 the deny mode specified includes bits not in effect for the open, the 7190 error NFS4ERR_INVAL should be returned. Since access and deny bits 7191 are subsets of those already granted, it is not possible for this 7192 request to be denied because of conflicting share reservations. 7194 On success, the current filehandle retains its value. 7196 ERRORS 7198 NFS4ERR_BADHANDLE 7200 Draft Specification NFS version 4 Protocol November 2001 7202 NFS4ERR_BAD_SEQID 7203 NFS4ERR_BAD_STATEID 7204 NFS4ERR_BADXDR 7205 NFS4ERR_EXPIRED 7206 NFS4ERR_FHEXPIRED 7207 NFS4ERR_INVAL 7208 NFS4ERR_MOVED 7209 NFS4ERR_NOFILEHANDLE 7210 NFS4ERR_OLD_STATEID 7211 NFS4ERR_RESOURCE 7212 NFS4ERR_SERVERFAULT 7213 NFS4ERR_STALE 7214 NFS4ERR_STALE_STATEID 7216 Draft Specification NFS version 4 Protocol November 2001 7218 14.2.20. Operation 22: PUTFH - Set Current Filehandle 7220 SYNOPSIS 7222 filehandle -> (cfh) 7224 ARGUMENT 7226 struct PUTFH4args { 7227 nfs_fh4 object; 7228 }; 7230 RESULT 7232 struct PUTFH4res { 7233 /* CURRENT_FH: */ 7234 nfsstat4 status; 7235 }; 7237 DESCRIPTION 7239 Replaces the current filehandle with the filehandle provided as an 7240 argument. 7242 IMPLEMENTATION 7244 Commonly used as the first operator in an NFS request to set the 7245 context for following operations. 7247 ERRORS 7249 NFS4ERR_BADHANDLE 7250 NFS4ERR_BADXDR 7251 NFS4ERR_FHEXPIRED 7252 NFS4ERR_MOVED 7253 NFS4ERR_RESOURCE 7254 NFS4ERR_SERVERFAULT 7255 NFS4ERR_STALE 7256 NFS4ERR_WRONGSEC 7258 Draft Specification NFS version 4 Protocol November 2001 7260 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle 7262 SYNOPSIS 7264 - -> (cfh) 7266 ARGUMENT 7268 void; 7270 RESULT 7272 struct PUTPUBFH4res { 7273 /* CURRENT_FH: public fh */ 7274 nfsstat4 status; 7275 }; 7277 DESCRIPTION 7279 Replaces the current filehandle with the filehandle that represents 7280 the public filehandle of the server's name space. This filehandle 7281 may be different from the "root" filehandle which may be associated 7282 with some other directory on the server. 7284 IMPLEMENTATION 7286 Used as the first operator in an NFS request to set the context for 7287 following operations. 7289 ERRORS 7291 NFS4ERR_RESOURCE 7292 NFS4ERR_SERVERFAULT 7293 NFS4ERR_WRONGSEC 7295 Draft Specification NFS version 4 Protocol November 2001 7297 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle 7299 SYNOPSIS 7301 - -> (cfh) 7303 ARGUMENT 7305 void; 7307 RESULT 7309 struct PUTROOTFH4res { 7310 /* CURRENT_FH: root fh */ 7311 nfsstat4 status; 7312 }; 7314 DESCRIPTION 7316 Replaces the current filehandle with the filehandle that represents 7317 the root of the server's name space. From this filehandle a LOOKUP 7318 operation can locate any other filehandle on the server. This 7319 filehandle may be different from the "public" filehandle which may 7320 be associated with some other directory on the server. 7322 IMPLEMENTATION 7324 Commonly used as the first operator in an NFS request to set the 7325 context for following operations. 7327 ERRORS 7329 NFS4ERR_RESOURCE 7330 NFS4ERR_SERVERFAULT 7331 NFS4ERR_WRONGSEC 7333 Draft Specification NFS version 4 Protocol November 2001 7335 14.2.23. Operation 25: READ - Read from File 7337 SYNOPSIS 7339 (cfh), offset, count, stateid -> eof, data 7341 ARGUMENT 7343 struct READ4args { 7344 /* CURRENT_FH: file */ 7345 stateid4 stateid; 7346 offset4 offset; 7347 count4 count; 7348 }; 7350 RESULT 7352 struct READ4resok { 7353 bool eof; 7354 opaque data<>; 7355 }; 7357 union READ4res switch (nfsstat4 status) { 7358 case NFS4_OK: 7359 READ4resok resok4; 7360 default: 7361 void; 7362 }; 7364 DESCRIPTION 7366 The READ operation reads data from the regular file identified by 7367 the current filehandle. 7369 The client provides an offset of where the READ is to start and a 7370 count of how many bytes are to be read. An offset of 0 (zero) 7371 means to read data starting at the beginning of the file. If 7372 offset is greater than or equal to the size of the file, the 7373 status, NFS4_OK, is returned with a data length set to 0 (zero) and 7374 eof is set to TRUE. The READ is subject to access permissions 7375 checking. 7377 If the client specifies a count value of 0 (zero), the READ 7378 succeeds and returns 0 (zero) bytes of data again subject to access 7379 permissions checking. The server may choose to return fewer bytes 7380 than specified by the client. The client needs to check for this 7381 condition and handle the condition appropriately. 7383 The stateid value for a READ request represents a value returned 7385 Draft Specification NFS version 4 Protocol November 2001 7387 from a previous record lock or share reservation request. Used by 7388 the server to verify that the associated lock is still valid and to 7389 update lease timeouts for the client. 7391 If the read ended at the end-of-file (formally, in a correctly 7392 formed READ request, if offset + count is equal to the size of the 7393 file), or the read request extends beyond the size of the file (if 7394 offset + count is greater than the size of the file), eof is 7395 returned as TRUE; otherwise it is FALSE. A successful READ of an 7396 empty file will always return eof as TRUE. 7398 If the current filehandle is not a regular file, an error will be 7399 returned to the client. In the case the current filehandle 7400 represents a directory, NFS4ERR_ISDIR is return; otherwise, 7401 NFS4ERR_INVAL is returned. 7403 On success, the current filehandle retains its value. 7405 IMPLEMENTATION 7407 It is possible for the server to return fewer than count bytes of 7408 data. If the server returns less than the count requested and eof 7409 set to FALSE, the client should issue another READ to get the 7410 remaining data. A server may return less data than requested under 7411 several circumstances. The file may have been truncated by another 7412 client or perhaps on the server itself, changing the file size from 7413 what the requesting client believes to be the case. This would 7414 reduce the actual amount of data available to the client. It is 7415 possible that the server may back off the transfer size and reduce 7416 the read request return. Server resource exhaustion may also occur 7417 necessitating a smaller read return. 7419 If the file is locked the server will return an NFS4ERR_LOCKED 7420 error. Since the lock may be of short duration, the client may 7421 choose to retransmit the READ request (with exponential backoff) 7422 until the operation succeeds. 7424 ERRORS 7426 NFS4ERR_ACCES 7427 NFS4ERR_BADHANDLE 7428 NFS4ERR_BAD_STATEID 7429 NFS4ERR_BADXDR 7430 NFS4ERR_DELAY 7431 NFS4ERR_DENIED 7432 NFS4ERR_EXPIRED 7433 NFS4ERR_FHEXPIRED 7434 NFS4ERR_GRACE 7435 NFS4ERR_INVAL 7436 NFS4ERR_IO 7438 Draft Specification NFS version 4 Protocol November 2001 7440 NFS4ERR_ISDIR 7441 NFS4ERR_LOCKED 7442 NFS4ERR_LEASE_MOVED 7443 NFS4ERR_MOVED 7444 NFS4ERR_NOFILEHANDLE 7445 NFS4ERR_NXIO 7446 NFS4ERR_OLD_STATEID 7447 NFS4ERR_RESOURCE 7448 NFS4ERR_SERVERFAULT 7449 NFS4ERR_STALE 7450 NFS4ERR_STALE_STATEID 7451 NFS4ERR_WRONGSEC 7453 Draft Specification NFS version 4 Protocol November 2001 7455 14.2.24. Operation 26: READDIR - Read Directory 7457 SYNOPSIS 7458 (cfh), cookie, cookieverf, dircount, maxcount, attr_request -> 7459 cookieverf { cookie, name, attributes } 7461 ARGUMENT 7463 struct READDIR4args { 7464 /* CURRENT_FH: directory */ 7465 nfs_cookie4 cookie; 7466 verifier4 cookieverf; 7467 count4 dircount; 7468 count4 maxcount; 7469 bitmap4 attr_request; 7470 }; 7472 RESULT 7474 struct entry4 { 7475 nfs_cookie4 cookie; 7476 component4 name; 7477 fattr4 attrs; 7478 entry4 *nextentry; 7479 }; 7481 struct dirlist4 { 7482 entry4 *entries; 7483 bool eof; 7484 }; 7486 struct READDIR4resok { 7487 verifier4 cookieverf; 7488 dirlist4 reply; 7489 }; 7491 union READDIR4res switch (nfsstat4 status) { 7492 case NFS4_OK: 7493 READDIR4resok resok4; 7494 default: 7495 void; 7496 }; 7498 DESCRIPTION 7500 The READDIR operation retrieves a variable number of entries from a 7501 file system directory and returns client requested attributes for 7502 each entry along with information to allow the client to request 7504 Draft Specification NFS version 4 Protocol November 2001 7506 additional directory entries in a subsequent READDIR. 7508 The arguments contain a cookie value that represents where the 7509 READDIR should start within the directory. A value of 0 (zero) for 7510 the cookie is used to start reading at the beginning of the 7511 directory. For subsequent READDIR requests, the client specifies a 7512 cookie value that is provided by the server on a previous READDIR 7513 request. 7515 The cookieverf value should be set to 0 (zero) when the cookie 7516 value is 0 (zero) (first directory read). On subsequent requests, 7517 it should be a cookieverf as returned by the server. The 7518 cookieverf must match that returned by the READDIR in which the 7519 cookie was acquired. 7521 The dircount portion of the argument is a hint of the maximum 7522 number of bytes of directory information that should be returned. 7523 This value represents the length of the names of the directory 7524 entries and the cookie value for these entries. This length 7525 represents the XDR encoding of the data (names and cookies) and not 7526 the length in the native format of the server. The server may 7527 return less data. 7529 The maxcount value of the argument is the maximum number of bytes 7530 for the result. This maximum size represents all of the data being 7531 returned and includes the XDR overhead. The server may return less 7532 data. If the server is unable to return a single directory entry 7533 within the maxcount limit, the error NFS4ERR_READDIR_NOSPC will be 7534 returned to the client. 7536 Finally, attrbits represents the list of attributes to be returned 7537 for each directory entry supplied by the server. 7539 On successful return, the server's response will provide a list of 7540 directory entries. Each of these entries contains the name of the 7541 directory entry, a cookie value for that entry, and the associated 7542 attributes as requested. 7544 The cookie value is only meaningful to the server and is used as a 7545 "bookmark" for the directory entry. As mentioned, this cookie is 7546 used by the client for subsequent READDIR operations so that it may 7547 continue reading a directory. The cookie is similar in concept to 7548 a READ offset but should not be interpreted as such by the client. 7549 Ideally, the cookie value should not change if the directory is 7550 modified since the client may be caching these values. 7552 In some cases, the server may encounter an error while obtaining 7553 the attributes for a directory entry. Instead of returning an 7554 error for the entire READDIR operation, the server can instead 7555 return the attribute 'fattr4_rdattr_error'. With this, the server 7556 is able to communicate the failure to the client and not fail the 7557 entire operation in the instance of what might be a transient 7559 Draft Specification NFS version 4 Protocol November 2001 7561 failure. Obviously, the client must request the 7562 fattr4_rdattr_error attribute for this method to work properly. If 7563 the client does not request the attribute, the server has no choice 7564 but to return failure for the entire READDIR operation. 7566 For some file system environments, the directory entries "." and 7567 ".." have special meaning and in other environments, they may not. 7568 If the server supports these special entries within a directory, 7569 they should not be returned to the client as part of the READDIR 7570 response. To enable some client environments, the cookie values of 7571 0, 1, and 2 are to be considered reserved. Note that the Unix 7572 client will use these values when combining the server's response 7573 and local representations to enable a fully formed Unix directory 7574 presentation to the application. 7576 For READDIR arguments, cookie values of 1 and 2 should not be used 7577 and for READDIR results cookie values of 0, 1, and 2 should not 7578 returned. 7580 On success, the current filehandle retains its value. 7582 IMPLEMENTATION 7584 The server's file system directory representations can differ 7585 greatly. A client's programming interfaces may also be bound to 7586 the local operating environment in a way that does not translate 7587 well into the NFS protocol. Therefore the use of the dircount and 7588 maxcount fields are provided to allow the client the ability to 7589 provide guidelines to the server. If the client is aggressive 7590 about attribute collection during a READDIR, the server has an idea 7591 of how to limit the encoded response. The dircount field provides 7592 a hint on the number of entries based solely on the names of the 7593 directory entries. Since it is a hint, it may be possible that a 7594 dircount value is zero. In this case, the server is free to ignore 7595 the dircount value and return directory information based on the 7596 specified maxcount value. 7598 The cookieverf may be used by the server to help manage cookie 7599 values that may become stale. It should be a rare occurrence that 7600 a server is unable to continue properly reading a directory with 7601 the provided cookie/cookieverf pair. The server should make every 7602 effort to avoid this condition since the application at the client 7603 may not be able to properly handle this type of failure. 7605 The use of the cookieverf will also protect the client from using 7606 READDIR cookie values that may be stale. For example, if the file 7607 system has been migrated, the server may or may not be able to use 7608 the same cookie values to service READDIR as the previous server 7609 used. With the client providing the cookieverf, the server is able 7610 to provide the appropriate response to the client. This prevents 7611 the case where the server may accept a cookie value but the 7613 Draft Specification NFS version 4 Protocol November 2001 7615 underlying directory has changed and the response is invalid from 7616 the client's context of its previous READDIR. 7618 Since some servers will not be returning "." and ".." entries as 7619 has been done with previous versions of the NFS protocol, the 7620 client that requires these entries be present in READDIR responses 7621 must fabricate them. 7623 ERRORS 7625 NFS4ERR_ACCES 7626 NFS4ERR_BADHANDLE 7627 NFS4ERR_BAD_COOKIE 7628 NFS4ERR_BADXDR 7629 NFS4ERR_DELAY 7630 NFS4ERR_FHEXPIRED 7631 NFS4ERR_INVAL 7632 NFS4ERR_IO 7633 NFS4ERR_MOVED 7634 NFS4ERR_NOFILEHANDLE 7635 NFS4ERR_NOTDIR 7636 NFS4ERR_NOTSUPP 7637 NFS4ERR_READDIR_NOSPC 7638 NFS4ERR_RESOURCE 7639 NFS4ERR_SERVERFAULT 7640 NFS4ERR_STALE 7641 NFS4ERR_TOOSMALL 7642 NFS4ERR_WRONGSEC 7644 Draft Specification NFS version 4 Protocol November 2001 7646 14.2.25. Operation 27: READLINK - Read Symbolic Link 7648 SYNOPSIS 7650 (cfh) -> linktext 7652 ARGUMENT 7654 /* CURRENT_FH: symlink */ 7655 void; 7657 RESULT 7659 struct READLINK4resok { 7660 linktext4 link; 7661 }; 7663 union READLINK4res switch (nfsstat4 status) { 7664 case NFS4_OK: 7665 READLINK4resok resok4; 7666 default: 7667 void; 7668 }; 7670 DESCRIPTION 7672 READLINK reads the data associated with a symbolic link. The data 7673 is a UTF-8 string that is opaque to the server. That is, whether 7674 created by an NFS client or created locally on the server, the data 7675 in a symbolic link is not interpreted when created, but is simply 7676 stored. 7678 On success, the current filehandle retains its value. 7680 IMPLEMENTATION 7682 A symbolic link is nominally a pointer to another file. The data 7683 is not necessarily interpreted by the server, just stored in the 7684 file. It is possible for a client implementation to store a path 7685 name that is not meaningful to the server operating system in a 7686 symbolic link. A READLINK operation returns the data to the client 7687 for interpretation. If different implementations want to share 7688 access to symbolic links, then they must agree on the 7689 interpretation of the data in the symbolic link. 7691 The READLINK operation is only allowed on objects of type NF4LNK. 7692 The server should return the error, NFS4ERR_INVAL, if the object is 7693 not of type, NF4LNK. 7695 Draft Specification NFS version 4 Protocol November 2001 7697 ERRORS 7699 NFS4ERR_ACCES 7700 NFS4ERR_BADHANDLE 7701 NFS4ERR_DELAY 7702 NFS4ERR_FHEXPIRED 7703 NFS4ERR_INVAL 7704 NFS4ERR_IO 7705 NFS4ERR_MOVED 7706 NFS4ERR_NOFILEHANDLE 7707 NFS4ERR_NOTSUPP 7708 NFS4ERR_RESOURCE 7709 NFS4ERR_SERVERFAULT 7710 NFS4ERR_STALE 7711 NFS4ERR_WRONGSEC 7713 Draft Specification NFS version 4 Protocol November 2001 7715 14.2.26. Operation 28: REMOVE - Remove Filesystem Object 7717 SYNOPSIS 7719 (cfh), filename -> change_info 7721 ARGUMENT 7723 struct REMOVE4args { 7724 /* CURRENT_FH: directory */ 7725 component4 target; 7726 }; 7728 RESULT 7730 struct REMOVE4resok { 7731 change_info4 cinfo; 7732 } 7734 union REMOVE4res switch (nfsstat4 status) { 7735 case NFS4_OK: 7736 REMOVE4resok resok4; 7737 default: 7738 void; 7739 } 7741 DESCRIPTION 7743 The REMOVE operation removes (deletes) a directory entry named by 7744 filename from the directory corresponding to the current 7745 filehandle. If the entry in the directory was the last reference 7746 to the corresponding file system object, the object may be 7747 destroyed. 7749 For the directory where the filename was removed, the server 7750 returns change_info4 information in cinfo. With the atomic field 7751 of the change_info4 struct, the server will indicate if the before 7752 and after change attributes were obtained atomically with respect 7753 to the removal. 7755 If the target has a length of 0 (zero), or if target does not obey 7756 the UTF-8 definition, the error NFS4ERR_INVAL will be returned. 7758 On success, the current filehandle retains its value. 7760 IMPLEMENTATION 7762 NFS versions 2 and 3 required a different operator RMDIR for 7764 Draft Specification NFS version 4 Protocol November 2001 7766 directory removal. NFS version 4 REMOVE can be used to delete any 7767 directory entry independent of its file type. 7769 The concept of last reference is server specific. However, if the 7770 numlinks field in the previous attributes of the object had the 7771 value 1, the client should not rely on referring to the object via 7772 a file handle. Likewise, the client should not rely on the 7773 resources (disk space, directory entry, and so on) formerly 7774 associated with the object becoming immediately available. Thus, if 7775 a client needs to be able to continue to access a file after using 7776 REMOVE to remove it, the client should take steps to make sure that 7777 the file will still be accessible. The usual mechanism used is to 7778 RENAME the file from its old name to a new hidden name. 7780 ERRORS 7782 NFS4ERR_ACCES 7783 NFS4ERR_BADHANDLE 7784 NFS4ERR_BADXDR 7785 NFS4ERR_DELAY 7786 NFS4ERR_FHEXPIRED 7787 NFS4ERR_INVAL 7788 NFS4ERR_IO 7789 NFS4ERR_MOVED 7790 NFS4ERR_NAMETOOLONG 7791 NFS4ERR_NOENT 7792 NFS4ERR_NOFILEHANDLE 7793 NFS4ERR_NOTDIR 7794 NFS4ERR_NOTEMPTY 7795 NFS4ERR_NOTSUPP 7796 NFS4ERR_RESOURCE 7797 NFS4ERR_ROFS 7798 NFS4ERR_SERVERFAULT 7799 NFS4ERR_STALE 7800 NFS4ERR_WRONGSEC 7802 Draft Specification NFS version 4 Protocol November 2001 7804 14.2.27. Operation 29: RENAME - Rename Directory Entry 7806 SYNOPSIS 7808 (sfh), oldname (cfh), newname -> source_change_info, 7809 target_change_info 7811 ARGUMENT 7813 struct RENAME4args { 7814 /* SAVED_FH: source directory */ 7815 component4 oldname; 7816 /* CURRENT_FH: target directory */ 7817 component4 newname; 7818 }; 7820 RESULT 7822 struct RENAME4resok { 7823 change_info4 source_cinfo; 7824 change_info4 target_cinfo; 7825 }; 7827 union RENAME4res switch (nfsstat4 status) { 7828 case NFS4_OK: 7829 RENAME4resok resok4; 7830 default: 7831 void; 7832 }; 7834 DESCRIPTION 7836 The RENAME operation renames the object identified by oldname in 7837 the source directory corresponding to the saved filehandle, as set 7838 by the SAVEFH operation, to newname in the target directory 7839 corresponding to the current filehandle. The operation is required 7840 to be atomic to the client. Source and target directories must 7841 reside on the same file system on the server. On success, the 7842 current filehandle will continue to be the target directory. 7844 If the target directory already contains an entry with the name, 7845 newname, the source object must be compatible with the target: 7846 either both are non-directories or both are directories and the 7847 target must be empty. If compatible, the existing target is 7848 removed before the rename occurs. If they are not compatible or if 7849 the target is a directory but not empty, the server will return the 7850 error, NFS4ERR_EXIST. 7852 If oldname and newname both refer to the same file (they might be 7854 Draft Specification NFS version 4 Protocol November 2001 7856 hard links of each other), then RENAME should perform no action and 7857 return success. 7859 For both directories involved in the RENAME, the server returns 7860 change_info4 information. With the atomic field of the 7861 change_info4 struct, the server will indicate if the before and 7862 after change attributes were obtained atomically with respect to 7863 the rename. 7865 If the oldname or newname has a length of 0 (zero), or if oldname 7866 or newname does not obey the UTF-8 definition, the error 7867 NFS4ERR_INVAL will be returned. 7869 IMPLEMENTATION 7871 The RENAME operation must be atomic to the client. The statement 7872 "source and target directories must reside on the same file system 7873 on the server" means that the fsid fields in the attributes for the 7874 directories are the same. If they reside on different file systems, 7875 the error, NFS4ERR_XDEV, is returned. 7877 A filehandle may or may not become stale or expire on a rename. 7878 However, server implementors are strongly encouraged to attempt to 7879 keep file handles from becoming stale or expiring in this fashion. 7881 On some servers, the filenames, "." and "..", are illegal as either 7882 oldname or newname. In addition, neither oldname nor newname can 7883 be an alias for the source directory. These servers will return 7884 the error, NFS4ERR_INVAL, in these cases. 7886 ERRORS 7888 NFS4ERR_ACCES 7889 NFS4ERR_BADHANDLE 7890 NFS4ERR_BADXDR 7891 NFS4ERR_DELAY 7892 NFS4ERR_DQUOT 7893 NFS4ERR_EXIST 7894 NFS4ERR_FHEXPIRED 7895 NFS4ERR_INVAL 7896 NFS4ERR_IO 7897 NFS4ERR_ISDIR 7898 NFS4ERR_MOVED 7899 NFS4ERR_NAMETOOLONG 7900 NFS4ERR_NOENT 7901 NFS4ERR_NOFILEHANDLE 7902 NFS4ERR_NOSPC 7903 NFS4ERR_NOTDIR 7904 NFS4ERR_NOTEMPTY 7906 Draft Specification NFS version 4 Protocol November 2001 7908 NFS4ERR_NOTSUPP 7909 NFS4ERR_RESOURCE 7910 NFS4ERR_ROFS 7911 NFS4ERR_SERVERFAULT 7912 NFS4ERR_STALE 7913 NFS4ERR_WRONGSEC 7914 NFS4ERR_XDEV 7916 Draft Specification NFS version 4 Protocol November 2001 7918 14.2.28. Operation 30: RENEW - Renew a Lease 7920 SYNOPSIS 7922 clientid -> () 7924 ARGUMENT 7926 struct RENEW4args { 7927 clientid4clientid; 7928 }; 7930 RESULT 7932 struct RENEW4res { 7933 nfsstat4 status; 7934 }; 7936 DESCRIPTION 7938 The RENEW operation is used by the client to renew leases which it 7939 currently holds at a server. In processing the RENEW request, the 7940 server renews all leases associated with the client. The 7941 associated leases are determined by the clientid provided via the 7942 SETCLIENTID procedure. 7944 IMPLEMENTATION 7946 ERRORS 7948 NFS4ERR_BADXDR 7949 NFS4ERR_EXPIRED 7950 NFS4ERR_GRACE 7951 NFS4ERR_INVAL 7952 NFS4ERR_LEASE_MOVED 7953 NFS4ERR_MOVED 7954 NFS4ERR_RESOURCE 7955 NFS4ERR_SERVERFAULT 7956 NFS4ERR_STALE_CLIENTID 7957 NFS4ERR_WRONGSEC 7959 Draft Specification NFS version 4 Protocol November 2001 7961 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle 7963 SYNOPSIS 7965 (sfh) -> (cfh) 7967 ARGUMENT 7969 /* SAVED_FH: */ 7970 void; 7972 RESULT 7974 struct RESTOREFH4res { 7975 /* CURRENT_FH: value of saved fh */ 7976 nfsstat4 status; 7977 }; 7979 DESCRIPTION 7981 Set the current filehandle to the value in the saved filehandle. 7982 If there is no saved filehandle then return an error 7983 NFS4ERR_NOFILEHANDLE. 7985 IMPLEMENTATION 7987 Operations like OPEN and LOOKUP use the current filehandle to 7988 represent a directory and replace it with a new filehandle. 7989 Assuming the previous filehandle was saved with a SAVEFH operator, 7990 the previous filehandle can be restored as the current filehandle. 7991 This is commonly used to obtain post-operation attributes for the 7992 directory, e.g. 7994 PUTFH (directory filehandle) 7995 SAVEFH 7996 GETATTR attrbits (pre-op dir attrs) 7997 CREATE optbits "foo" attrs 7998 GETATTR attrbits (file attributes) 7999 RESTOREFH 8000 GETATTR attrbits (post-op dir attrs) 8002 ERRORS 8004 NFS4ERR_BADHANDLE 8005 NFS4ERR_FHEXPIRED 8006 NFS4ERR_MOVED 8008 Draft Specification NFS version 4 Protocol November 2001 8010 NFS4ERR_NOFILEHANDLE 8011 NFS4ERR_RESOURCE 8012 NFS4ERR_SERVERFAULT 8013 NFS4ERR_STALE 8014 NFS4ERR_WRONGSEC 8016 Draft Specification NFS version 4 Protocol November 2001 8018 14.2.30. Operation 32: SAVEFH - Save Current Filehandle 8020 SYNOPSIS 8022 (cfh) -> (sfh) 8024 ARGUMENT 8026 /* CURRENT_FH: */ 8027 void; 8029 RESULT 8031 struct SAVEFH4res { 8032 /* SAVED_FH: value of current fh */ 8033 nfsstat4 status; 8034 }; 8036 DESCRIPTION 8038 Save the current filehandle. If a previous filehandle was saved 8039 then it is no longer accessible. The saved filehandle can be 8040 restored as the current filehandle with the RESTOREFH operator. 8042 On success, the current filehandle retains its value. 8044 IMPLEMENTATION 8046 ERRORS 8048 NFS4ERR_BADHANDLE 8049 NFS4ERR_FHEXPIRED 8050 NFS4ERR_MOVED 8051 NFS4ERR_NOFILEHANDLE 8052 NFS4ERR_RESOURCE 8053 NFS4ERR_SERVERFAULT 8054 NFS4ERR_STALE 8055 NFS4ERR_WRONGSEC 8057 Draft Specification NFS version 4 Protocol November 2001 8059 14.2.31. Operation 33: SECINFO - Obtain Available Security 8061 SYNOPSIS 8063 (cfh), name -> { secinfo } 8065 ARGUMENT 8067 struct SECINFO4args { 8068 /* CURRENT_FH: */ 8069 component4 name; 8070 }; 8072 RESULT 8074 enum rpc_gss_svc_t { 8075 RPC_GSS_SVC_NONE = 1, 8076 RPC_GSS_SVC_INTEGRITY = 2, 8077 RPC_GSS_SVC_PRIVACY = 3 8078 }; 8080 struct rpcsec_gss_info { 8081 sec_oid4 oid; 8082 qop4 qop; 8083 rpc_gss_svc_t service; 8084 }; 8086 union secinfo4 switch (uint32_t flavor) { 8087 case RPCSEC_GSS: 8088 rpcsec_gss_info flavor_info; 8089 default: 8090 void; 8091 }; 8093 typedef secinfo4 SECINFO4resok<>; 8095 union SECINFO4res switch (nfsstat4 status) { 8096 case NFS4_OK: 8097 SECINFO4resok resok4; 8098 default: 8099 void; 8100 }; 8102 DESCRIPTION 8104 The SECINFO operation is used by the client to obtain a list of 8105 valid RPC authentication flavors for a specific file handle, file 8106 name pair. The result will contain an array which represents the 8108 Draft Specification NFS version 4 Protocol November 2001 8110 security mechanisms available. The array entries are represented 8111 by the secinfo4 structure. The field 'flavor' will contain a value 8112 of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or RPCSEC_GSS (as 8113 defined in [RFC2203]). 8115 For the flavors, AUTH_NONE, and AUTH_SYS no additional security 8116 information is returned. For a return value of RPCSEC_GSS, a 8117 security triple is returned that contains the mechanism object id 8118 (as defined in [RFC2078]), the quality of protection (as defined in 8119 [RFC2078]) and the service type (as defined in [RFC2203]). It is 8120 possible for SECINFO to return multiple entries with flavor equal 8121 to RPCSEC_GSS with different security triple values. 8123 On success, the current filehandle retains its value. 8125 IMPLEMENTATION 8127 The SECINFO operation is expected to be used by the NFS client when 8128 the error value of NFS4ERR_WRONGSEC is returned from another NFS 8129 operation. This signifies to the client that the server's security 8130 policy is different from what the client is currently using. At 8131 this point, the client is expected to obtain a list of possible 8132 security flavors and choose what best suits its policies. 8134 It is recommended that the client issue the SECINFO call protected 8135 by a security triple that uses either rpc_gss_svc_integrity or 8136 rpc_gss_svc_privacy service. The use of rpc_gss_svc_none would 8137 allow an attacker in the middle to modify the SECINFO results such 8138 that the client might select a weaker algorithm in the set allowed 8139 by server, making the client and/or server vulnerable to further 8140 attacks. 8142 ERRORS 8144 NFS4ERR_ACCESS 8145 NFS4ERR_BADHANDLE 8146 NFS4ERR_BADXDR 8147 NFS4ERR_FHEXPIRED 8148 NFS4ERR_MOVED 8149 NFS4ERR_NAMETOOLONG 8150 NFS4ERR_NOENT 8151 NFS4ERR_NOFILEHANDLE 8152 NFS4ERR_NOTDIR 8153 NFS4ERR_RESOURCE 8154 NFS4ERR_SERVERFAULT 8155 NFS4ERR_STALE 8156 NFS4ERR_WRONGSEC 8158 Draft Specification NFS version 4 Protocol November 2001 8160 14.2.32. Operation 34: SETATTR - Set Attributes 8162 SYNOPSIS 8164 (cfh), attrbits, attrvals -> - 8166 ARGUMENT 8168 struct SETATTR4args { 8169 /* CURRENT_FH: target object */ 8170 stateid4 stateid; 8171 fattr4 obj_attributes; 8172 }; 8174 RESULT 8176 struct SETATTR4res { 8177 nfsstat4 status; 8178 bitmap4 attrsset; 8179 }; 8181 DESCRIPTION 8183 The SETATTR operation changes one or more of the attributes of a 8184 file system object. The new attributes are specified with a bitmap 8185 and the attributes that follow the bitmap in bit order. 8187 The stateid is necessary for SETATTRs that change the size of a 8188 file (modify the attribute object_size). This stateid represents a 8189 record lock, share reservation, or delegation which must be valid 8190 for the SETATTR to modify the file data. A valid stateid would 8191 always be specified. When the file size is not changed, the 8192 special stateid consisting of all bits 0 (zero) should be used. 8194 On either success or failure of the operation, the server will 8195 return the attrsset bitmask to represent what (if any) attributes 8196 were successfully set. 8198 On success, the current filehandle retains its value. 8200 IMPLEMENTATION 8202 The file size attribute is used to request changes to the size of a 8203 file. A value of 0 (zero) causes the file to be truncated, a value 8204 less than the current size of the file causes data from new size to 8205 the end of the file to be discarded, and a size greater than the 8206 current size of the file causes logically zeroed data bytes to be 8207 added to the end of the file. Servers are free to implement this 8209 Draft Specification NFS version 4 Protocol November 2001 8211 using holes or actual zero data bytes. Clients should not make any 8212 assumptions regarding a server's implementation of this feature, 8213 beyond that the bytes returned will be zeroed. Servers must 8214 support extending the file size via SETATTR. 8216 SETATTR is not guaranteed atomic. A failed SETATTR may partially 8217 change a file's attributes. 8219 Changing the size of a file with SETATTR indirectly changes the 8220 time_modify. A client must account for this as size changes can 8221 result in data deletion. 8223 If server and client times differ, programs that compare client 8224 time to file times can break. A time maintenance protocol should be 8225 used to limit client/server time skew. 8227 If the server cannot successfully set all the attributes it must 8228 return an NFS4ERR_INVAL error. If the server can only support 32 8229 bit offsets and sizes, a SETATTR request to set the size of a file 8230 to larger than can be represented in 32 bits will be rejected with 8231 this same error. 8233 ERRORS 8235 NFS4ERR_ACCES 8236 NFS4ERR_ATTRNOTSUPP 8237 NFS4ERR_BADHANDLE 8238 NFS4ERR_BAD_STATEID 8239 NFS4ERR_BADXDR 8240 NFS4ERR_DELAY 8241 NFS4ERR_DENIED 8242 NFS4ERR_DQUOT 8243 NFS4ERR_EXPIRED 8244 NFS4ERR_FBIG 8245 NFS4ERR_FHEXPIRED 8246 NFS4ERR_GRACE 8247 NFS4ERR_INVAL 8248 NFS4ERR_IO 8249 NFS4ERR_MOVED 8250 NFS4ERR_NOFILEHANDLE 8251 NFS4ERR_NOSPC 8252 NFS4ERR_NOTSUPP 8253 NFS4ERR_OLD_STATEID 8254 NFS4ERR_PERM 8255 NFS4ERR_RESOURCE 8256 NFS4ERR_ROFS 8257 NFS4ERR_SERVERFAULT 8258 NFS4ERR_STALE 8259 NFS4ERR_STALE_STATEID 8260 NFS4ERR_WRONGSEC 8262 Draft Specification NFS version 4 Protocol November 2001 8264 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid 8266 SYNOPSIS 8268 client, callback -> clientid 8270 ARGUMENT 8272 struct SETCLIENTID4args { 8273 nfs_client_id4 client; 8274 cb_client4 callback; 8275 }; 8277 RESULT 8279 struct SETCLIENTID4resok { 8280 clientid4 clientid; 8281 }; 8283 union SETCLIENTID4res switch (nfsstat4 status) { 8284 case NFS4_OK: 8285 SETCLIENTID4resok resok4; 8286 case NFS4ERR_CLID_INUSE: 8287 clientaddr4 client_using; 8288 default: 8289 void; 8290 }; 8292 DESCRIPTION 8294 The SETCLIENTID operation introduces the ability of the client to 8295 notify the server of its intention to use a particular client 8296 identifier and verifier pair. Upon successful completion the 8297 server will return a clientid which is used in subsequent file 8298 locking requests and for a confirmation step. The client will use 8299 the SETCLIENTID_CONFIRM operation to return the clientid, as a 8300 verifier, to the server. At that point, the client may use the 8301 clientid in subsequent operations that require an nfs_lockowner. 8303 The callback information provided in this operation will be used if 8304 the client is provided an open delegation at a future point. 8305 Therefore, the client must correctly reflect the program and port 8306 numbers for the callback program at the time SETCLIENTID is used. 8308 IMPLEMENTATION 8310 The server takes the verifier and client identification supplied in 8311 the nfs_client_id4 and searches for a match of the client 8313 Draft Specification NFS version 4 Protocol November 2001 8315 identification. If no match is found the server saves the 8316 principal/uid information along with the verifier and client 8317 identification and returns a unique clientid that is used as a 8318 shorthand reference to the supplied information. 8320 If the server finds matching client identification and a 8321 corresponding match in principal/uid, the server releases all 8322 locking state for the client and returns a new clientid. 8324 The principal, or principal to user-identifier mapping is taken 8325 from the credential presented in the RPC. As mentioned, the server 8326 will use the credential and associated principal for the matching 8327 with existing clientids. If the client is a traditional host-based 8328 client like a Unix NFS client, then the credential presented may be 8329 the host credential. If the client is a user level client or 8330 lightweight client, the credential used may be the end user's 8331 credential. The client should take care in choosing an appropriate 8332 credential since denial of service attacks could be attempted by a 8333 rogue client that has access to the credential. 8335 ERRORS 8337 NFS4ERR_BADXDR 8338 NFS4ERR_CLID_INUSE 8339 NFS4ERR_INVAL 8340 NFS4ERR_RESOURCE 8341 NFS4ERR_SERVERFAULT 8343 Draft Specification NFS version 4 Protocol November 2001 8345 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 8347 SYNOPSIS 8349 clientid -> - 8351 ARGUMENT 8353 struct SETCLIENTID_CONFIRM4args { 8354 clientid4 clientid; 8355 }; 8357 RESULT 8359 struct SETCLIENTID_CONFIRM4res { 8360 nfsstat4 status; 8361 }; 8363 DESCRIPTION 8365 This operation is used by the client to confirm the results from a 8366 previous call to SETCLIENTID. The client provides the server 8367 supplied (from a SETCLIENTID response) clientid. The server 8368 responds with a simple status of success or failure. 8370 IMPLEMENTATION 8372 The client must use the SETCLIENTID_CONFIRM operation to confirm 8373 its use of client identifier. If the server is holding state for a 8374 client which has presented a new verifier via SETCLIENTID, then the 8375 state will not be released, as described in the section "Client 8376 Failure and Recovery", until a valid SETCLIENTID_CONFIRM is 8377 received. Upon successful confirmation the server will release the 8378 previous state held on behalf of the client. The server should 8379 choose a confirmation cookie value that is reasonably unique for 8380 the client. 8382 ERRORS 8384 NFS4ERR_BADXDR 8385 NFS4ERR_CLID_INUSE 8386 NFS4ERR_INVAL 8387 NFS4ERR_RESOURCE 8388 NFS4ERR_SERVERFAULT 8389 NFS4ERR_STALE_CLIENTID 8391 Draft Specification NFS version 4 Protocol November 2001 8393 14.2.35. Operation 37: VERIFY - Verify Same Attributes 8395 SYNOPSIS 8397 (cfh), fattr -> - 8399 ARGUMENT 8401 struct VERIFY4args { 8402 /* CURRENT_FH: object */ 8403 fattr4 obj_attributes; 8404 }; 8406 RESULT 8408 struct VERIFY4res { 8409 nfsstat4 status; 8410 }; 8412 DESCRIPTION 8414 The VERIFY operation is used to verify that attributes have a value 8415 assumed by the client before proceeding with following operations 8416 in the compound request. If any of the attributes do not match 8417 then the error NFS4ERR_NOT_SAME must be returned. The current 8418 filehandle retains its value after successful completion of the 8419 operation. 8421 IMPLEMENTATION 8423 One possible use of the VERIFY operation is the following compound 8424 sequence. With this the client is attempting to verify that the 8425 file being removed will match what the client expects to be 8426 removed. This sequence can help prevent the unintended deletion of 8427 a file. 8429 PUTFH (directory filehandle) 8430 LOOKUP (file name) 8431 VERIFY (filehandle == fh) 8432 PUTFH (directory filehandle) 8433 REMOVE (file name) 8435 This sequence does not prevent a second client from removing and 8436 creating a new file in the middle of this sequence but it does help 8437 avoid the unintended result. 8439 In the case that a recommended attribute is specified in the VERIFY 8440 operation and the server does not support that attribute for the 8441 file system object, the error NFS4ERR_NOTSUPP is returned to the 8443 Draft Specification NFS version 4 Protocol November 2001 8445 client. 8447 ERRORS 8449 NFS4ERR_ACCES 8450 NFS4ERR_ATTRNOTSUPP 8451 NFS4ERR_BADHANDLE 8452 NFS4ERR_BADXDR 8453 NFS4ERR_DELAY 8454 NFS4ERR_FHEXPIRED 8455 NFS4ERR_INVAL 8456 NFS4ERR_MOVED 8457 NFS4ERR_NOFILEHANDLE 8458 NFS4ERR_NOTSUPP 8459 NFS4ERR_NOT_SAME 8460 NFS4ERR_RESOURCE 8461 NFS4ERR_SERVERFAULT 8462 NFS4ERR_STALE 8463 NFS4ERR_WRONGSEC 8465 Draft Specification NFS version 4 Protocol November 2001 8467 14.2.36. Operation 38: WRITE - Write to File 8469 SYNOPSIS 8471 (cfh), offset, count, stability, stateid, data -> count, committed, 8472 verifier 8474 ARGUMENT 8476 enum stable_how4 { 8477 UNSTABLE4 = 0, 8478 DATA_SYNC4 = 1, 8479 FILE_SYNC4 = 2 8480 }; 8482 struct WRITE4args { 8483 /* CURRENT_FH: file */ 8484 stateid4 stateid; 8485 offset4 offset; 8486 stable_how4 stable; 8487 opaque data<>; 8488 }; 8490 RESULT 8492 struct WRITE4resok { 8493 count4 count; 8494 stable_how4 committed; 8495 verifier4 writeverf; 8496 }; 8498 union WRITE4res switch (nfsstat4 status) { 8499 case NFS4_OK: 8500 WRITE4resok resok4; 8501 default: 8502 void; 8503 }; 8505 DESCRIPTION 8507 The WRITE operation is used to write data to a regular file. The 8508 target file is specified by the current filehandle. The offset 8509 specifies the offset where the data should be written. An offset 8510 of 0 (zero) specifies that the write should start at the beginning 8511 of the file. The count represents the number of bytes of data that 8512 are to be written. If the count is 0 (zero), the WRITE will 8513 succeed and return a count of 0 (zero) subject to permissions 8514 checking. The server may choose to write fewer bytes than 8515 requested by the client. 8517 Draft Specification NFS version 4 Protocol November 2001 8519 Part of the write request is a specification of how the write is to 8520 be performed. The client specifies with the stable parameter the 8521 method of how the data is to be processed by the server. If stable 8522 is FILE_SYNC4, the server must commit the data written plus all 8523 file system metadata to stable storage before returning results. 8524 This corresponds to the NFS version 2 protocol semantics. Any 8525 other behavior constitutes a protocol violation. If stable is 8526 DATA_SYNC4, then the server must commit all of the data to stable 8527 storage and enough of the metadata to retrieve the data before 8528 returning. The server implementor is free to implement DATA_SYNC4 8529 in the same fashion as FILE_SYNC4, but with a possible performance 8530 drop. If stable is UNSTABLE4, the server is free to commit any 8531 part of the data and the metadata to stable storage, including all 8532 or none, before returning a reply to the client. There is no 8533 guarantee whether or when any uncommitted data will subsequently be 8534 committed to stable storage. The only guarantees made by the server 8535 are that it will not destroy any data without changing the value of 8536 verf and that it will not commit the data and metadata at a level 8537 less than that requested by the client. 8539 The stateid returned from a previous record lock or share 8540 reservation request is provided as part of the argument. The 8541 stateid is used by the server to verify that the associated lock is 8542 still valid and to update lease timeouts for the client. 8544 Upon successful completion, the following results are returned. 8545 The count result is the number of bytes of data written to the 8546 file. The server may write fewer bytes than requested. If so, the 8547 actual number of bytes written starting at location, offset, is 8548 returned. 8550 The server also returns an indication of the level of commitment of 8551 the data and metadata via committed. If the server committed all 8552 data and metadata to stable storage, committed should be set to 8553 FILE_SYNC4. If the level of commitment was at least as strong as 8554 DATA_SYNC4, then committed should be set to DATA_SYNC4. Otherwise, 8555 committed must be returned as UNSTABLE4. If stable was FILE4_SYNC, 8556 then committed must also be FILE_SYNC4: anything else constitutes a 8557 protocol violation. If stable was DATA_SYNC4, then committed may be 8558 FILE_SYNC4 or DATA_SYNC4: anything else constitutes a protocol 8559 violation. If stable was UNSTABLE4, then committed may be either 8560 FILE_SYNC4, DATA_SYNC4, or UNSTABLE4. 8562 The final portion of the result is the write verifier, verf. The 8563 write verifier is a cookie that the client can use to determine 8564 whether the server has changed state between a call to WRITE and a 8565 subsequent call to either WRITE or COMMIT. This cookie must be 8566 consistent during a single instance of the NFS version 4 protocol 8567 service and must be unique between instances of the NFS version 4 8568 protocol server, where uncommitted data may be lost. 8570 If a client writes data to the server with the stable argument set 8572 Draft Specification NFS version 4 Protocol November 2001 8574 to UNSTABLE4 and the reply yields a committed response of 8575 DATA_SYNC4 or UNSTABLE4, the client will follow up some time in the 8576 future with a COMMIT operation to synchronize outstanding 8577 asynchronous data and metadata with the server's stable storage, 8578 barring client error. It is possible that due to client crash or 8579 other error that a subsequent COMMIT will not be received by the 8580 server. 8582 On success, the current filehandle retains its value. 8584 IMPLEMENTATION 8586 It is possible for the server to write fewer than count bytes of 8587 data. In this case, the server should not return an error unless 8588 no data was written at all. If the server writes less than count 8589 bytes, the client should issue another WRITE to write the remaining 8590 data. 8592 It is assumed that the act of writing data to a file will cause the 8593 time_modified of the file to be updated. However, the 8594 time_modified of the file should not be changed unless the contents 8595 of the file are changed. Thus, a WRITE request with count set to 0 8596 should not cause the time_modified of the file to be updated. 8598 The definition of stable storage has been historically a point of 8599 contention. The following expected properties of stable storage 8600 may help in resolving design issues in the implementation. Stable 8601 storage is persistent storage that survives: 8603 1. Repeated power failures. 8604 2. Hardware failures (of any board, power supply, etc.). 8605 3. Repeated software crashes, including reboot cycle. 8607 This definition does not address failure of the stable storage 8608 module itself. 8610 The verifier is defined to allow a client to detect different 8611 instances of an NFS version 4 protocol server over which cached, 8612 uncommitted data may be lost. In the most likely case, the verifier 8613 allows the client to detect server reboots. This information is 8614 required so that the client can safely determine whether the server 8615 could have lost cached data. If the server fails unexpectedly and 8616 the client has uncommitted data from previous WRITE requests (done 8617 with the stable argument set to UNSTABLE4 and in which the result 8618 committed was returned as UNSTABLE4 as well) it may not have 8619 flushed cached data to stable storage. The burden of recovery is on 8620 the client and the client will need to retransmit the data to the 8621 server. 8623 Draft Specification NFS version 4 Protocol November 2001 8625 A suggested verifier would be to use the time that the server was 8626 booted or the time the server was last started (if restarting the 8627 server without a reboot results in lost buffers). 8629 The committed field in the results allows the client to do more 8630 effective caching. If the server is committing all WRITE requests 8631 to stable storage, then it should return with committed set to 8632 FILE_SYNC4, regardless of the value of the stable field in the 8633 arguments. A server that uses an NVRAM accelerator may choose to 8634 implement this policy. The client can use this to increase the 8635 effectiveness of the cache by discarding cached data that has 8636 already been committed on the server. 8638 Some implementations may return NFS4ERR_NOSPC instead of 8639 NFS4ERR_DQUOT when a user's quota is exceeded. 8641 ERRORS 8643 NFS4ERR_ACCES 8644 NFS4ERR_BADHANDLE 8645 NFS4ERR_BAD_STATEID 8646 NFS4ERR_BADXDR 8647 NFS4ERR_DELAY 8648 NFS4ERR_DENIED 8649 NFS4ERR_DQUOT 8650 NFS4ERR_EXPIRED 8651 NFS4ERR_FBIG 8652 NFS4ERR_FHEXPIRED 8653 NFS4ERR_GRACE 8654 NFS4ERR_INVAL 8655 NFS4ERR_IO 8656 NFS4ERR_LEASE_MOVED 8657 NFS4ERR_LOCKED 8658 NFS4ERR_MOVED 8659 NFS4ERR_NOFILEHANDLE 8660 NFS4ERR_NOSPC 8661 NFS4ERR_OLD_STATEID 8662 NFS4ERR_RESOURCE 8663 NFS4ERR_ROFS 8664 NFS4ERR_SERVERFAULT 8665 NFS4ERR_STALE 8666 NFS4ERR_STALE_STATEID 8667 NFS4ERR_WRONGSEC 8669 Draft Specification NFS version 4 Protocol November 2001 8671 15. NFS Version 4 Callback Procedures 8673 The procedures used for callbacks are defined in the following 8674 sections. In the interest of clarity, the terms "client" and 8675 "server" refer to NFS clients and servers, despite the fact that for 8676 an individual callback RPC, the sense of these terms would be 8677 precisely the opposite. 8679 15.1. Procedure 0: CB_NULL - No Operation 8681 SYNOPSIS 8683 8685 ARGUMENT 8687 void; 8689 RESULT 8691 void; 8693 DESCRIPTION 8695 Standard NULL procedure. Void argument, void response. Even 8696 though there is no direct functionality associated with this 8697 procedure, the server will use CB_NULL to confirm the existence of 8698 a path for RPCs from server to client. 8700 ERRORS 8702 None. 8704 Draft Specification NFS version 4 Protocol November 2001 8706 15.2. Procedure 1: CB_COMPOUND - Compound Operations 8708 SYNOPSIS 8710 compoundargs -> compoundres 8712 ARGUMENT 8714 enum nfs_cb_opnum4 { 8715 OP_CB_GETATTR = 3, 8716 OP_CB_RECALL = 4 8717 }; 8719 union nfs_cb_argop4 switch (unsigned argop) { 8720 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 8721 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 8722 }; 8724 struct CB_COMPOUND4args { 8725 utf8string tag; 8726 uint32_t minorversion; 8727 nfs_cb_argop4 argarray<>; 8728 }; 8730 RESULT 8732 union nfs_cb_resop4 switch (unsigned resop){ 8733 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 8734 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 8735 }; 8737 struct CB_COMPOUND4res { 8738 nfsstat4 status; 8739 utf8string tag; 8740 nfs_cb_resop4 resarray<>; 8741 }; 8743 DESCRIPTION 8745 The CB_COMPOUND procedure is used to combine one or more of the 8746 callback procedures into a single RPC request. The main callback 8747 RPC program has two main procedures: CB_NULL and CB_COMPOUND. All 8748 other operations use the CB_COMPOUND procedure as a wrapper. 8750 In the processing of the CB_COMPOUND procedure, the client may find 8751 that it does not have the available resources to execute any or all 8752 of the operations within the CB_COMPOUND sequence. In this case, 8753 the error NFS4ERR_RESOURCE will be returned for the particular 8754 operation within the CB_COMPOUND procedure where the resource 8756 Draft Specification NFS version 4 Protocol November 2001 8758 exhaustion occurred. This assumes that all previous operations 8759 within the CB_COMPOUND sequence have been evaluated successfully. 8761 Contained within the CB_COMPOUND results is a 'status' field. This 8762 status must be equivalent to the status of the last operation that 8763 was executed within the CB_COMPOUND procedure. Therefore, if an 8764 operation incurred an error then the 'status' value will be the 8765 same error value as is being returned for the operation that 8766 failed. 8768 IMPLEMENTATION 8770 The CB_COMPOUND procedure is used to combine individual operations 8771 into a single RPC request. The client interprets each of the 8772 operations in turn. If an operation is executed by the client and 8773 the status of that operation is NFS4_OK, then the next operation in 8774 the CB_COMPOUND procedure is executed. The client continues this 8775 process until there are no more operations to be executed or one of 8776 the operations has a status value other than NFS4_OK. 8778 ERRORS 8780 NFS4ERR_BADHANDLE 8781 NFS4ERR_BAD_STATEID 8782 NFS4ERR_RESOURCE 8784 Draft Specification NFS version 4 Protocol November 2001 8786 15.2.1. Operation 3: CB_GETATTR - Get Attributes 8788 SYNOPSIS 8790 fh, attrbits -> attrbits, attrvals 8792 ARGUMENT 8794 struct CB_GETATTR4args { 8795 nfs_fh4 fh; 8796 bitmap4 attr_request; 8797 }; 8799 RESULT 8801 struct CB_GETATTR4resok { 8802 fattr4 obj_attributes; 8803 }; 8805 union CB_GETATTR4res switch (nfsstat4 status) { 8806 case NFS4_OK: 8807 CB_GETATTR4resok resok4; 8808 default: 8809 void; 8810 }; 8812 DESCRIPTION 8814 The CB_GETATTR operation is used to obtain the attributes modified 8815 by an open delegate to allow the server to respond to GETATTR 8816 requests for a file which is the subject of an open delegation. 8818 If the handle specified is not one for which the client holds a 8819 write open delegation, an NFS4ERR_BADHANDLE error is returned. 8821 IMPLEMENTATION 8823 The client returns attrbits and the associated attribute values 8824 only for attributes that it may change (change, time_modify, 8825 object_size). 8827 ERRORS 8829 NFS4ERR_BADHANDLE 8830 NFS4ERR_BADXDR 8831 NFS4ERR_RESOURCE 8833 Draft Specification NFS version 4 Protocol November 2001 8835 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation 8837 SYNOPSIS 8839 stateid, truncate, fh -> status 8841 ARGUMENT 8843 struct CB_RECALL4args { 8844 stateid4 stateid; 8845 bool truncate; 8846 nfs_fh4 fh; 8847 }; 8849 RESULT 8851 struct CB_RECALL4res { 8852 nfsstat4 status; 8853 }; 8855 DESCRIPTION 8857 The CB_RECALL operation is used to begin the process of recalling 8858 an open delegation and returning it to the server. 8860 The truncate flag is used to optimize recall for a file which is 8861 about to be truncated to zero. When it is set, the client is freed 8862 of obligation to propagate modified data for the file to the 8863 server, since this data is irrelevant. 8865 If the handle specified is not one for which the client holds an 8866 open delegation, an NFS4ERR_BADHANDLE error is returned. 8868 If the stateid specified is not one corresponding to an open 8869 delegation for the file specified by the filehandle, an 8870 NFS4ERR_BAD_STATEID is returned. 8872 IMPLEMENTATION 8874 The client should reply to the callback immediately. Replying does 8875 not complete the recall. The recall is not complete until the 8876 delegation is returned using a DELEGRETURN. 8878 ERRORS 8880 NFS4ERR_BADHANDLE 8881 NFS4ERR_BAD_STATEID 8883 Draft Specification NFS version 4 Protocol November 2001 8885 NFS4ERR_BADXDR 8886 NFS4ERR_RESOURCE 8888 Draft Specification NFS version 4 Protocol November 2001 8890 16. Security Considerations 8892 The major security feature to consider is the authentication of the 8893 user making the request of NFS service. Consideration should also be 8894 given to the integrity and privacy of this NFS request. These 8895 specific issues are discussed as part of the section on "RPC and 8896 Security Flavor". 8898 Draft Specification NFS version 4 Protocol November 2001 8900 17. IANA Considerations 8902 17.1. Named Attribute Definition 8904 The NFS version 4 protocol provides for the association of named 8905 attributes to files. The name space identifiers for these attributes 8906 are defined as string names. The protocol does not define the 8907 specific assignment of the name space for these file attributes; the 8908 application developer or system vendor is allowed to define the 8909 attribute, its semantics, and the associated name. Even though this 8910 name space will not be specifically controlled to prevent collisions, 8911 the application developer or system vendor is strongly encouraged to 8912 provide the name assignment and associated semantics for attributes 8913 via an Informational RFC. This will provide for interoperability 8914 where common interests exist. 8916 Draft Specification NFS version 4 Protocol November 2001 8918 18. RPC definition file 8920 /* 8921 * Copyright (C) The Internet Society (1998,1999,2000,2001). 8922 * All Rights Reserved. 8923 */ 8925 /* 8926 * nfs4_prot.x 8927 * 8928 */ 8930 %#pragma ident "@(#)nfs4_prot.x 1.104 01/11/14" 8932 /* 8933 * Basic typedefs for RFC 1832 data type definitions 8934 */ 8935 typedef int int32_t; 8936 typedef unsigned int uint32_t; 8937 typedef hyper int64_t; 8938 typedef unsigned hyper uint64_t; 8940 /* 8941 * Sizes 8942 */ 8943 const NFS4_FHSIZE = 128; 8944 const NFS4_VERIFIER_SIZE = 8; 8946 /* 8947 * File types 8948 */ 8949 enum nfs_ftype4 { 8950 NF4REG = 1, /* Regular File */ 8951 NF4DIR = 2, /* Directory */ 8952 NF4BLK = 3, /* Special File - block device */ 8953 NF4CHR = 4, /* Special File - character device */ 8954 NF4LNK = 5, /* Symbolic Link */ 8955 NF4SOCK = 6, /* Special File - socket */ 8956 NF4FIFO = 7, /* Special File - fifo */ 8957 NF4ATTRDIR = 8, /* Attribute Directory */ 8958 NF4NAMEDATTR = 9 /* Named Attribute */ 8959 }; 8961 /* 8962 * Error status 8963 */ 8964 enum nfsstat4 { 8965 NFS4_OK = 0, 8966 NFS4ERR_PERM = 1, 8967 NFS4ERR_NOENT = 2, 8968 NFS4ERR_IO = 5, 8969 NFS4ERR_NXIO = 6, 8971 Draft Specification NFS version 4 Protocol November 2001 8973 NFS4ERR_ACCES = 13, 8974 NFS4ERR_EXIST = 17, 8975 NFS4ERR_XDEV = 18, 8976 NFS4ERR_NODEV = 19, 8977 NFS4ERR_NOTDIR = 20, 8978 NFS4ERR_ISDIR = 21, 8979 NFS4ERR_INVAL = 22, 8980 NFS4ERR_FBIG = 27, 8981 NFS4ERR_NOSPC = 28, 8982 NFS4ERR_ROFS = 30, 8983 NFS4ERR_MLINK = 31, 8984 NFS4ERR_NAMETOOLONG = 63, 8985 NFS4ERR_NOTEMPTY = 66, 8986 NFS4ERR_DQUOT = 69, 8987 NFS4ERR_STALE = 70, 8988 NFS4ERR_BADHANDLE = 10001, 8989 NFS4ERR_BAD_COOKIE = 10003, 8990 NFS4ERR_NOTSUPP = 10004, 8991 NFS4ERR_TOOSMALL = 10005, 8992 NFS4ERR_SERVERFAULT = 10006, 8993 NFS4ERR_BADTYPE = 10007, 8994 NFS4ERR_DELAY = 10008, 8995 NFS4ERR_SAME = 10009,/* nverify says attrs same */ 8996 NFS4ERR_DENIED = 10010,/* lock unavailable */ 8997 NFS4ERR_EXPIRED = 10011,/* lock lease expired */ 8998 NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ 8999 NFS4ERR_GRACE = 10013,/* in grace period */ 9000 NFS4ERR_FHEXPIRED = 10014,/* file handle expired */ 9001 NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ 9002 NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ 9003 NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ 9004 NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ 9005 NFS4ERR_MOVED = 10019,/* filesystem relocated */ 9006 NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */ 9007 NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */ 9008 NFS4ERR_STALE_CLIENTID = 10022, 9009 NFS4ERR_STALE_STATEID = 10023, 9010 NFS4ERR_OLD_STATEID = 10024, 9011 NFS4ERR_BAD_STATEID = 10025, 9012 NFS4ERR_BAD_SEQID = 10026, 9013 NFS4ERR_NOT_SAME = 10027,/* verify - attrs not same */ 9014 NFS4ERR_LOCK_RANGE = 10028, 9015 NFS4ERR_SYMLINK = 10029, 9016 NFS4ERR_READDIR_NOSPC = 10030, 9017 NFS4ERR_LEASE_MOVED = 10031, 9018 NFS4ERR_ATTRNOTSUPP = 10032, 9019 NFS4ERR_NO_GRACE = 10033, 9020 NFS4ERR_RECLAIM_BAD = 10034, 9021 NFS4ERR_RECLAIM_CONFLICT = 10035, 9022 NFS4ERR_BADXDR = 10036, 9023 NFS4ERR_LOCKS_HELD = 10037 9024 }; 9026 Draft Specification NFS version 4 Protocol November 2001 9028 /* 9029 * Basic data types 9030 */ 9031 typedef uint32_t bitmap4<>; 9032 typedef uint64_t offset4; 9033 typedef uint32_t count4; 9034 typedef uint64_t length4; 9035 typedef uint64_t clientid4; 9036 typedef uint32_t seqid4; 9037 typedef opaque utf8string<>; 9038 typedef utf8string component4; 9039 typedef component4 pathname4<>; 9040 typedef uint64_t nfs_lockid4; 9041 typedef uint64_t nfs_cookie4; 9042 typedef utf8string linktext4; 9043 typedef opaque sec_oid4<>; 9044 typedef uint32_t qop4; 9045 typedef uint32_t mode4; 9046 typedef uint64_t changeid4; 9047 typedef opaque verifier4[NFS4_VERIFIER_SIZE]; 9049 /* 9050 * Timeval 9051 */ 9052 struct nfstime4 { 9053 int64_t seconds; 9054 uint32_t nseconds; 9055 }; 9057 enum time_how4 { 9058 SET_TO_SERVER_TIME4 = 0, 9059 SET_TO_CLIENT_TIME4 = 1 9060 }; 9062 union settime4 switch (time_how4 set_it) { 9063 case SET_TO_CLIENT_TIME4: 9064 nfstime4 time; 9065 default: 9066 void; 9067 }; 9069 /* 9070 * File access handle 9071 */ 9072 typedef opaque nfs_fh4; 9074 /* 9075 * File attribute definitions 9076 */ 9078 /* 9080 Draft Specification NFS version 4 Protocol November 2001 9082 * FSID structure for major/minor 9083 */ 9084 struct fsid4 { 9085 uint64_t major; 9086 uint64_t minor; 9087 }; 9089 /* 9090 * Filesystem locations attribute for relocation/migration 9091 */ 9092 struct fs_location4 { 9093 utf8string server<>; 9094 pathname4 rootpath; 9095 }; 9097 struct fs_locations4 { 9098 pathname4 fs_root; 9099 fs_location4 locations<>; 9100 }; 9102 /* 9103 * Various Access Control Entry definitions 9104 */ 9106 /* 9107 * Mask that indicates which Access Control Entries are supported. 9108 * Values for the fattr4_aclsupport attribute. 9109 */ 9110 const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; 9111 const ACL4_SUPPORT_DENY_ACL = 0x00000002; 9112 const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; 9113 const ACL4_SUPPORT_ALARM_ACL = 0x00000008; 9115 typedef uint32_t acetype4; 9117 /* 9118 * acetype4 values, others can be added as needed. 9119 */ 9120 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; 9121 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; 9122 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; 9123 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; 9125 /* 9126 * ACE flag 9127 */ 9128 typedef uint32_t aceflag4; 9130 /* 9131 * ACE flag values 9133 Draft Specification NFS version 4 Protocol November 2001 9135 */ 9136 const ACE4_FILE_INHERIT_ACE = 0x00000001; 9137 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; 9138 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; 9139 const ACE4_INHERIT_ONLY_ACE = 0x00000008; 9140 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; 9141 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; 9142 const ACE4_IDENTIFIER_GROUP = 0x00000040; 9144 /* 9145 * ACE mask 9146 */ 9147 typedef uint32_t acemask4; 9149 /* 9150 * ACE mask values 9151 */ 9152 const ACE4_READ_DATA = 0x00000001; 9153 const ACE4_LIST_DIRECTORY = 0x00000001; 9154 const ACE4_WRITE_DATA = 0x00000002; 9155 const ACE4_ADD_FILE = 0x00000002; 9156 const ACE4_APPEND_DATA = 0x00000004; 9157 const ACE4_ADD_SUBDIRECTORY = 0x00000004; 9158 const ACE4_READ_NAMED_ATTRS = 0x00000008; 9159 const ACE4_WRITE_NAMED_ATTRS = 0x00000010; 9160 const ACE4_EXECUTE = 0x00000020; 9161 const ACE4_DELETE_CHILD = 0x00000040; 9162 const ACE4_READ_ATTRIBUTES = 0x00000080; 9163 const ACE4_WRITE_ATTRIBUTES = 0x00000100; 9165 const ACE4_DELETE = 0x00010000; 9166 const ACE4_READ_ACL = 0x00020000; 9167 const ACE4_WRITE_ACL = 0x00040000; 9168 const ACE4_WRITE_OWNER = 0x00080000; 9169 const ACE4_SYNCHRONIZE = 0x00100000; 9171 /* 9172 * ACE4_GENERIC_READ -- defined as combination of 9173 * ACE4_READ_ACL | 9174 * ACE4_READ_DATA | 9175 * ACE4_READ_ATTRIBUTES | 9176 * ACE4_SYNCHRONIZE 9177 */ 9179 const ACE4_GENERIC_READ = 0x00120081; 9181 /* 9182 * ACE4_GENERIC_WRITE -- defined as combination of 9183 * ACE4_READ_ACL | 9184 * ACE4_WRITE_DATA | 9185 * ACE4_WRITE_ATTRIBUTES | 9187 Draft Specification NFS version 4 Protocol November 2001 9189 * ACE4_WRITE_ACL | 9190 * ACE4_APPEND_DATA | 9191 * ACE4_SYNCHRONIZE 9192 */ 9193 const ACE4_GENERIC_WRITE = 0x00160106; 9195 /* 9196 * ACE4_GENERIC_EXECUTE -- defined as combination of 9197 * ACE4_READ_ACL 9198 * ACE4_READ_ATTRIBUTES 9199 * ACE4_EXECUTE 9200 * ACE4_SYNCHRONIZE 9201 */ 9202 const ACE4_GENERIC_EXECUTE = 0x001200A0; 9204 /* 9205 * Access Control Entry definition 9206 */ 9207 struct nfsace4 { 9208 acetype4 type; 9209 aceflag4 flag; 9210 acemask4 access_mask; 9211 utf8string who; 9212 }; 9214 /* 9215 * Special data/attribute associated with 9216 * file types NF4BLK and NF4CHR. 9217 */ 9218 struct specdata4 { 9219 uint32_t specdata1; 9220 uint32_t specdata2; 9221 }; 9223 /* 9224 * Values for fattr4_fh_expire_type 9225 */ 9226 const FH4_PERSISTENT = 0x00000000; 9227 const FH4_NOEXPIRE_WITH_OPEN = 0x00000001; 9228 const FH4_VOLATILE_ANY = 0x00000002; 9229 const FH4_VOL_MIGRATION = 0x00000004; 9230 const FH4_VOL_RENAME = 0x00000008; 9232 typedef bitmap4 fattr4_supported_attrs; 9233 typedef nfs_ftype4 fattr4_type; 9234 typedef uint32_t fattr4_fh_expire_type; 9235 typedef changeid4 fattr4_change; 9236 typedef uint64_t fattr4_size; 9237 typedef bool fattr4_link_support; 9239 Draft Specification NFS version 4 Protocol November 2001 9241 typedef bool fattr4_symlink_support; 9242 typedef bool fattr4_named_attr; 9243 typedef fsid4 fattr4_fsid; 9244 typedef bool fattr4_unique_handles; 9245 typedef uint32_t fattr4_lease_time; 9246 typedef nfsstat4 fattr4_rdattr_error; 9248 typedef nfsace4 fattr4_acl<>; 9249 typedef uint32_t fattr4_aclsupport; 9250 typedef bool fattr4_archive; 9251 typedef bool fattr4_cansettime; 9252 typedef bool fattr4_case_insensitive; 9253 typedef bool fattr4_case_preserving; 9254 typedef bool fattr4_chown_restricted; 9255 typedef uint64_t fattr4_fileid; 9256 typedef uint64_t fattr4_files_avail; 9257 typedef nfs_fh4 fattr4_filehandle; 9258 typedef uint64_t fattr4_files_free; 9259 typedef uint64_t fattr4_files_total; 9260 typedef fs_locations4 fattr4_fs_locations; 9261 typedef bool fattr4_hidden; 9262 typedef bool fattr4_homogeneous; 9263 typedef uint64_t fattr4_maxfilesize; 9264 typedef uint32_t fattr4_maxlink; 9265 typedef uint32_t fattr4_maxname; 9266 typedef uint64_t fattr4_maxread; 9267 typedef uint64_t fattr4_maxwrite; 9268 typedef utf8string fattr4_mimetype; 9269 typedef mode4 fattr4_mode; 9270 typedef bool fattr4_no_trunc; 9271 typedef uint32_t fattr4_numlinks; 9272 typedef utf8string fattr4_owner; 9273 typedef utf8string fattr4_owner_group; 9274 typedef uint64_t fattr4_quota_avail_hard; 9275 typedef uint64_t fattr4_quota_avail_soft; 9276 typedef uint64_t fattr4_quota_used; 9277 typedef specdata4 fattr4_rawdev; 9278 typedef uint64_t fattr4_space_avail; 9279 typedef uint64_t fattr4_space_free; 9280 typedef uint64_t fattr4_space_total; 9281 typedef uint64_t fattr4_space_used; 9282 typedef bool fattr4_system; 9283 typedef nfstime4 fattr4_time_access; 9284 typedef settime4 fattr4_time_access_set; 9285 typedef nfstime4 fattr4_time_backup; 9286 typedef nfstime4 fattr4_time_create; 9287 typedef nfstime4 fattr4_time_delta; 9288 typedef nfstime4 fattr4_time_metadata; 9289 typedef nfstime4 fattr4_time_modify; 9290 typedef settime4 fattr4_time_modify_set; 9292 Draft Specification NFS version 4 Protocol November 2001 9294 /* 9295 * Mandatory Attributes 9296 */ 9297 const FATTR4_SUPPORTED_ATTRS = 0; 9298 const FATTR4_TYPE = 1; 9299 const FATTR4_FH_EXPIRE_TYPE = 2; 9300 const FATTR4_CHANGE = 3; 9301 const FATTR4_SIZE = 4; 9302 const FATTR4_LINK_SUPPORT = 5; 9303 const FATTR4_SYMLINK_SUPPORT = 6; 9304 const FATTR4_NAMED_ATTR = 7; 9305 const FATTR4_FSID = 8; 9306 const FATTR4_UNIQUE_HANDLES = 9; 9307 const FATTR4_LEASE_TIME = 10; 9308 const FATTR4_RDATTR_ERROR = 11; 9310 /* 9311 * Recommended Attributes 9312 */ 9313 const FATTR4_ACL = 12; 9314 const FATTR4_ACLSUPPORT = 13; 9315 const FATTR4_ARCHIVE = 14; 9316 const FATTR4_CANSETTIME = 15; 9317 const FATTR4_CASE_INSENSITIVE = 16; 9318 const FATTR4_CASE_PRESERVING = 17; 9319 const FATTR4_CHOWN_RESTRICTED = 18; 9320 const FATTR4_FILEHANDLE = 19; 9321 const FATTR4_FILEID = 20; 9322 const FATTR4_FILES_AVAIL = 21; 9323 const FATTR4_FILES_FREE = 22; 9324 const FATTR4_FILES_TOTAL = 23; 9325 const FATTR4_FS_LOCATIONS = 24; 9326 const FATTR4_HIDDEN = 25; 9327 const FATTR4_HOMOGENEOUS = 26; 9328 const FATTR4_MAXFILESIZE = 27; 9329 const FATTR4_MAXLINK = 28; 9330 const FATTR4_MAXNAME = 29; 9331 const FATTR4_MAXREAD = 30; 9332 const FATTR4_MAXWRITE = 31; 9333 const FATTR4_MIMETYPE = 32; 9334 const FATTR4_MODE = 33; 9335 const FATTR4_NO_TRUNC = 34; 9336 const FATTR4_NUMLINKS = 35; 9337 const FATTR4_OWNER = 36; 9338 const FATTR4_OWNER_GROUP = 37; 9339 const FATTR4_QUOTA_AVAIL_HARD = 38; 9340 const FATTR4_QUOTA_AVAIL_SOFT = 39; 9341 const FATTR4_QUOTA_USED = 40; 9342 const FATTR4_RAWDEV = 41; 9343 const FATTR4_SPACE_AVAIL = 42; 9344 const FATTR4_SPACE_FREE = 43; 9345 const FATTR4_SPACE_TOTAL = 44; 9347 Draft Specification NFS version 4 Protocol November 2001 9349 const FATTR4_SPACE_USED = 45; 9350 const FATTR4_SYSTEM = 46; 9351 const FATTR4_TIME_ACCESS = 47; 9352 const FATTR4_TIME_ACCESS_SET = 48; 9353 const FATTR4_TIME_BACKUP = 49; 9354 const FATTR4_TIME_CREATE = 50; 9355 const FATTR4_TIME_DELTA = 51; 9356 const FATTR4_TIME_METADATA = 52; 9357 const FATTR4_TIME_MODIFY = 53; 9358 const FATTR4_TIME_MODIFY_SET = 54; 9360 typedef opaque attrlist4<>; 9362 /* 9363 * File attribute container 9364 */ 9365 struct fattr4 { 9366 bitmap4 attrmask; 9367 attrlist4 attr_vals; 9368 }; 9370 /* 9371 * Change info for the client 9372 */ 9373 struct change_info4 { 9374 bool atomic; 9375 changeid4 before; 9376 changeid4 after; 9377 }; 9379 struct clientaddr4 { 9380 /* see struct rpcb in RFC 1833 */ 9381 string r_netid<>; /* network id */ 9382 string r_addr<>; /* universal address */ 9383 }; 9385 /* 9386 * Callback program info as provided by the client 9387 */ 9388 struct cb_client4 { 9389 uint32_t cb_program; 9390 clientaddr4 cb_location; 9391 }; 9393 /* 9394 * Stateid 9395 */ 9396 struct stateid4 { 9397 uint32_t seqid; 9398 opaque other[12]; 9399 }; 9401 Draft Specification NFS version 4 Protocol November 2001 9403 /* 9404 * Client ID 9405 */ 9406 struct nfs_client_id4 { 9407 verifier4 verifier; 9408 opaque id<>; 9409 }; 9411 struct open_owner4 { 9412 clientid4 clientid; 9413 opaque owner<>; 9414 }; 9416 struct lock_owner4 { 9417 clientid4 clientid; 9418 opaque owner<>; 9419 }; 9421 enum nfs_lock_type4 { 9422 READ_LT = 1, 9423 WRITE_LT = 2, 9424 READW_LT = 3, /* blocking read */ 9425 WRITEW_LT = 4, /* blocking write */ 9426 RELEASE_STATE = 5 /* release lock_stateid at server */ 9427 }; 9429 /* 9430 * ACCESS: Check access permission 9431 */ 9432 const ACCESS4_READ = 0x00000001; 9433 const ACCESS4_LOOKUP = 0x00000002; 9434 const ACCESS4_MODIFY = 0x00000004; 9435 const ACCESS4_EXTEND = 0x00000008; 9436 const ACCESS4_DELETE = 0x00000010; 9437 const ACCESS4_EXECUTE = 0x00000020; 9439 struct ACCESS4args { 9440 /* CURRENT_FH: object */ 9441 uint32_t access; 9442 }; 9444 struct ACCESS4resok { 9445 uint32_t supported; 9446 uint32_t access; 9447 }; 9449 union ACCESS4res switch (nfsstat4 status) { 9450 case NFS4_OK: 9451 ACCESS4resok resok4; 9452 default: 9453 void; 9454 }; 9456 Draft Specification NFS version 4 Protocol November 2001 9458 /* 9459 * CLOSE: Close a file and release share locks 9460 */ 9461 struct CLOSE4args { 9462 /* CURRENT_FH: object */ 9463 seqid4 seqid; 9464 stateid4 open_stateid; 9465 }; 9467 union CLOSE4res switch (nfsstat4 status) { 9468 case NFS4_OK: 9469 stateid4 open_stateid; 9470 default: 9471 void; 9472 }; 9474 /* 9475 * COMMIT: Commit cached data on server to stable storage 9476 */ 9477 struct COMMIT4args { 9478 /* CURRENT_FH: file */ 9479 offset4 offset; 9480 count4 count; 9481 }; 9483 struct COMMIT4resok { 9484 verifier4 writeverf; 9485 }; 9487 union COMMIT4res switch (nfsstat4 status) { 9488 case NFS4_OK: 9489 COMMIT4resok resok4; 9490 default: 9491 void; 9492 }; 9494 /* 9495 * CREATE: Create a non-regular file 9496 */ 9497 union createtype4 switch (nfs_ftype4 type) { 9498 case NF4LNK: 9499 linktext4 linkdata; 9500 case NF4BLK: 9501 case NF4CHR: 9502 specdata4 devdata; 9503 case NF4SOCK: 9504 case NF4FIFO: 9505 case NF4DIR: 9506 void; 9507 default: 9508 void; /* server should return NFS4ERR_BADTYPE */ 9510 Draft Specification NFS version 4 Protocol November 2001 9512 }; 9514 struct CREATE4args { 9515 /* CURRENT_FH: directory for creation */ 9516 createtype4 objtype; 9517 component4 objname; 9518 fattr4 createattrs; 9519 }; 9521 struct CREATE4resok { 9522 change_info4 cinfo; 9523 bitmap4 attrset; /* attributes set */ 9524 }; 9526 union CREATE4res switch (nfsstat4 status) { 9527 case NFS4_OK: 9528 CREATE4resok resok4; 9529 default: 9530 void; 9531 }; 9533 /* 9534 * DELEGPURGE: Purge Delegations Awaiting Recovery 9535 */ 9536 struct DELEGPURGE4args { 9537 clientid4 clientid; 9538 }; 9540 struct DELEGPURGE4res { 9541 nfsstat4 status; 9542 }; 9544 /* 9545 * DELEGRETURN: Return a delegation 9546 */ 9547 struct DELEGRETURN4args { 9548 stateid4 deleg_stateid; 9549 }; 9551 struct DELEGRETURN4res { 9552 nfsstat4 status; 9553 }; 9555 /* 9556 * GETATTR: Get file attributes 9557 */ 9558 struct GETATTR4args { 9559 /* CURRENT_FH: directory or file */ 9560 bitmap4 attr_request; 9561 }; 9563 struct GETATTR4resok { 9565 Draft Specification NFS version 4 Protocol November 2001 9567 fattr4 obj_attributes; 9568 }; 9570 union GETATTR4res switch (nfsstat4 status) { 9571 case NFS4_OK: 9572 GETATTR4resok resok4; 9573 default: 9574 void; 9575 }; 9577 /* 9578 * GETFH: Get current filehandle 9579 */ 9580 struct GETFH4resok { 9581 nfs_fh4 object; 9582 }; 9584 union GETFH4res switch (nfsstat4 status) { 9585 case NFS4_OK: 9586 GETFH4resok resok4; 9587 default: 9588 void; 9589 }; 9591 /* 9592 * LINK: Create link to an object 9593 */ 9594 struct LINK4args { 9595 /* SAVED_FH: source object */ 9596 /* CURRENT_FH: target directory */ 9597 component4 newname; 9598 }; 9600 struct LINK4resok { 9601 change_info4 cinfo; 9602 }; 9604 union LINK4res switch (nfsstat4 status) { 9605 case NFS4_OK: 9606 LINK4resok resok4; 9607 default: 9608 void; 9609 }; 9611 /* 9612 * For LOCK, transition from open_owner to new lock_owner 9613 */ 9614 struct open_to_lock_owner4 { 9615 seqid4 open_seqid; 9616 stateid4 open_stateid; 9617 seqid4 lock_seqid; 9618 lock_owner4 lock_owner; 9620 Draft Specification NFS version 4 Protocol November 2001 9622 }; 9624 /* 9625 * For LOCK, existing lock_owner continues to request file locks 9626 */ 9627 struct exist_lock_owner4 { 9628 stateid4 lock_stateid; 9629 seqid4 lock_seqid; 9630 }; 9632 union locker4 switch (bool new_lock_owner) { 9633 case TRUE: 9634 open_to_lock_owner4 open_owner; 9635 case FALSE: 9636 exist_lock_owner4 lock_owner; 9637 }; 9639 /* 9640 * LOCK/LOCKT/LOCKU: Record lock management 9641 */ 9642 struct LOCK4args { 9643 /* CURRENT_FH: file */ 9644 nfs_lock_type4 locktype; 9645 bool reclaim; 9646 offset4 offset; 9647 length4 length; 9648 locker4 locker; 9649 }; 9651 struct LOCK4denied { 9652 offset4 offset; 9653 length4 length; 9654 nfs_lock_type4 locktype; 9655 lock_owner4 owner; 9656 }; 9658 struct LOCK4resok { 9659 stateid4 lock_stateid; 9660 }; 9662 union LOCK4res switch (nfsstat4 status) { 9663 case NFS4_OK: 9664 LOCK4resok resok4; 9665 case NFS4ERR_DENIED: 9666 LOCK4denied denied; 9667 default: 9668 void; 9669 }; 9671 struct LOCKT4args { 9672 /* CURRENT_FH: file */ 9673 nfs_lock_type4 locktype; 9675 Draft Specification NFS version 4 Protocol November 2001 9677 offset4 offset; 9678 length4 length; 9679 lock_owner4 owner; 9680 }; 9682 union LOCKT4res switch (nfsstat4 status) { 9683 case NFS4ERR_DENIED: 9684 LOCK4denied denied; 9685 case NFS4_OK: 9686 void; 9687 default: 9688 void; 9689 }; 9691 struct LOCKU4args { 9692 /* CURRENT_FH: file */ 9693 nfs_lock_type4 locktype; 9694 seqid4 seqid; 9695 stateid4 lock_stateid; 9696 offset4 offset; 9697 length4 length; 9698 }; 9700 union LOCKU4res switch (nfsstat4 status) { 9701 case NFS4_OK: 9702 stateid4 lock_stateid; 9703 default: 9704 void; 9705 }; 9707 /* 9708 * LOOKUP: Lookup filename 9709 */ 9710 struct LOOKUP4args { 9711 /* CURRENT_FH: directory */ 9712 component4 objname; 9713 }; 9715 struct LOOKUP4res { 9716 /* CURRENT_FH: object */ 9717 nfsstat4 status; 9718 }; 9720 /* 9721 * LOOKUPP: Lookup parent directory 9722 */ 9723 struct LOOKUPP4res { 9724 /* CURRENT_FH: directory */ 9725 nfsstat4 status; 9726 }; 9728 /* 9730 Draft Specification NFS version 4 Protocol November 2001 9732 * NVERIFY: Verify attributes different 9733 */ 9734 struct NVERIFY4args { 9735 /* CURRENT_FH: object */ 9736 fattr4 obj_attributes; 9737 }; 9739 struct NVERIFY4res { 9740 nfsstat4 status; 9741 }; 9743 /* 9744 * Various definitions for OPEN 9745 */ 9746 enum createmode4 { 9747 UNCHECKED4 = 0, 9748 GUARDED4 = 1, 9749 EXCLUSIVE4 = 2 9750 }; 9752 union createhow4 switch (createmode4 mode) { 9753 case UNCHECKED4: 9754 case GUARDED4: 9755 fattr4 createattrs; 9756 case EXCLUSIVE4: 9757 verifier4 createverf; 9758 }; 9760 enum opentype4 { 9761 OPEN4_NOCREATE = 0, 9762 OPEN4_CREATE = 1 9763 }; 9765 union openflag4 switch (opentype4 opentype) { 9766 case OPEN4_CREATE: 9767 createhow4 how; 9768 default: 9769 void; 9770 }; 9772 /* Next definitions used for OPEN delegation */ 9773 enum limit_by4 { 9774 NFS_LIMIT_SIZE = 1, 9775 NFS_LIMIT_BLOCKS = 2 9776 /* others as needed */ 9777 }; 9779 struct nfs_modified_limit4 { 9780 uint32_t num_blocks; 9781 uint32_t bytes_per_block; 9782 }; 9784 Draft Specification NFS version 4 Protocol November 2001 9786 union nfs_space_limit4 switch (limit_by4 limitby) { 9787 /* limit specified as file size */ 9788 case NFS_LIMIT_SIZE: 9789 uint64_t filesize; 9790 /* limit specified by number of blocks */ 9791 case NFS_LIMIT_BLOCKS: 9792 nfs_modified_limit4 mod_blocks; 9793 } ; 9795 /* 9796 * Share Access and Deny constants for open argument 9797 */ 9798 const OPEN4_SHARE_ACCESS_READ = 0x00000001; 9799 const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; 9800 const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; 9802 const OPEN4_SHARE_DENY_NONE = 0x00000000; 9803 const OPEN4_SHARE_DENY_READ = 0x00000001; 9804 const OPEN4_SHARE_DENY_WRITE = 0x00000002; 9805 const OPEN4_SHARE_DENY_BOTH = 0x00000003; 9807 enum open_delegation_type4 { 9808 OPEN_DELEGATE_NONE = 0, 9809 OPEN_DELEGATE_READ = 1, 9810 OPEN_DELEGATE_WRITE = 2 9811 }; 9813 enum open_claim_type4 { 9814 CLAIM_NULL = 0, 9815 CLAIM_PREVIOUS = 1, 9816 CLAIM_DELEGATE_CUR = 2, 9817 CLAIM_DELEGATE_PREV = 3 9818 }; 9820 struct open_claim_delegate_cur4 { 9821 stateid4 delegate_stateid; 9822 component4 file; 9823 }; 9825 union open_claim4 switch (open_claim_type4 claim) { 9826 /* 9827 * No special rights to file. Ordinary OPEN of the specified file. 9828 */ 9829 case CLAIM_NULL: 9830 /* CURRENT_FH: directory */ 9831 component4 file; 9833 /* 9834 * Right to the file established by an open previous to server 9835 * reboot. File identified by filehandle obtained at that time 9836 * rather than by name. 9837 */ 9839 Draft Specification NFS version 4 Protocol November 2001 9841 case CLAIM_PREVIOUS: 9842 /* CURRENT_FH: file being reclaimed */ 9843 open_delegation_type4 delegate_type; 9845 /* 9846 * Right to file based on a delegation granted by the server. 9847 * File is specified by name. 9848 */ 9849 case CLAIM_DELEGATE_CUR: 9850 /* CURRENT_FH: directory */ 9851 open_claim_delegate_cur4 delegate_cur_info; 9853 /* Right to file based on a delegation granted to a previous boot 9854 * instance of the client. File is specified by name. 9855 */ 9856 case CLAIM_DELEGATE_PREV: 9857 /* CURRENT_FH: directory */ 9858 component4 file_delegate_prev; 9859 }; 9861 /* 9862 * OPEN: Open a file, potentially receiving an open delegation 9863 */ 9864 struct OPEN4args { 9865 seqid4 seqid; 9866 uint32_t share_access; 9867 uint32_t share_deny; 9868 open_owner4 owner; 9869 openflag4 openhow; 9870 open_claim4 claim; 9871 }; 9873 struct open_read_delegation4 { 9874 stateid4 stateid; /* Stateid for delegation*/ 9875 bool recall; /* Pre-recalled flag for 9876 delegations obtained 9877 by reclaim 9878 (CLAIM_PREVIOUS) */ 9879 nfsace4 permissions; /* Defines users who don't 9880 need an ACCESS call to 9881 open for read */ 9882 }; 9884 struct open_write_delegation4 { 9885 stateid4 stateid; /* Stateid for delegation */ 9886 bool recall; /* Pre-recalled flag for 9887 delegations obtained 9888 by reclaim 9889 (CLAIM_PREVIOUS) */ 9890 nfs_space_limit4 space_limit; /* Defines condition that 9891 the client must check to 9892 determine whether the 9894 Draft Specification NFS version 4 Protocol November 2001 9896 file needs to be flushed 9897 to the server on close. 9898 */ 9899 nfsace4 permissions; /* Defines users who don't 9900 need an ACCESS call as 9901 part of a delegated 9902 open. */ 9903 }; 9905 union open_delegation4 9906 switch (open_delegation_type4 delegation_type) { 9907 case OPEN_DELEGATE_NONE: 9908 void; 9909 case OPEN_DELEGATE_READ: 9910 open_read_delegation4 read; 9911 case OPEN_DELEGATE_WRITE: 9912 open_write_delegation4 write; 9913 }; 9915 /* 9916 * Result flags 9917 */ 9918 /* Mandatory locking is in effect for this file. */ 9919 const OPEN4_RESULT_MLOCK = 0x00000001; 9920 /* Client must confirm open */ 9921 const OPEN4_RESULT_CONFIRM = 0x00000002; 9923 struct OPEN4resok { 9924 stateid4 stateid; /* Stateid for open */ 9925 change_info4 cinfo; /* Directory Change Info */ 9926 uint32_t rflags; /* Result flags */ 9927 bitmap4 attrset; /* attribute set for create*/ 9928 open_delegation4 delegation; /* Info on any open 9929 delegation */ 9930 }; 9932 union OPEN4res switch (nfsstat4 status) { 9933 case NFS4_OK: 9934 /* CURRENT_FH: opened file */ 9935 OPEN4resok resok4; 9936 default: 9937 void; 9938 }; 9940 /* 9941 * OPENATTR: open named attributes directory 9942 */ 9943 struct OPENATTR4args { 9944 /* CURRENT_FH: object */ 9945 bool createdir; 9946 }; 9948 Draft Specification NFS version 4 Protocol November 2001 9950 struct OPENATTR4res { 9951 /* CURRENT_FH: named attr directory */ 9952 nfsstat4 status; 9953 }; 9955 /* 9956 * OPEN_CONFIRM: confirm the open 9957 */ 9958 struct OPEN_CONFIRM4args { 9959 /* CURRENT_FH: opened file */ 9960 stateid4 open_stateid; 9961 seqid4 seqid; 9962 }; 9964 struct OPEN_CONFIRM4resok { 9965 stateid4 open_stateid; 9966 }; 9968 union OPEN_CONFIRM4res switch (nfsstat4 status) { 9969 case NFS4_OK: 9970 OPEN_CONFIRM4resok resok4; 9971 default: 9972 void; 9973 }; 9975 /* 9976 * OPEN_DOWNGRADE: downgrade the access/deny for a file 9977 */ 9978 struct OPEN_DOWNGRADE4args { 9979 /* CURRENT_FH: opened file */ 9980 stateid4 open_stateid; 9981 seqid4 seqid; 9982 uint32_t share_access; 9983 uint32_t share_deny; 9984 }; 9986 struct OPEN_DOWNGRADE4resok { 9987 stateid4 open_stateid; 9988 }; 9990 union OPEN_DOWNGRADE4res switch(nfsstat4 status) { 9991 case NFS4_OK: 9992 OPEN_DOWNGRADE4resok resok4; 9993 default: 9994 void; 9995 }; 9997 /* 9998 * PUTFH: Set current filehandle 9999 */ 10000 struct PUTFH4args { 10001 nfs_fh4 object; 10003 Draft Specification NFS version 4 Protocol November 2001 10005 }; 10007 struct PUTFH4res { 10008 /* CURRENT_FH: */ 10009 nfsstat4 status; 10010 }; 10012 /* 10013 * PUTPUBFH: Set public filehandle 10014 */ 10015 struct PUTPUBFH4res { 10016 /* CURRENT_FH: public fh */ 10017 nfsstat4 status; 10018 }; 10020 /* 10021 * PUTROOTFH: Set root filehandle 10022 */ 10023 struct PUTROOTFH4res { 10024 /* CURRENT_FH: root fh */ 10025 nfsstat4 status; 10026 }; 10028 /* 10029 * READ: Read from file 10030 */ 10031 struct READ4args { 10032 /* CURRENT_FH: file */ 10033 stateid4 stateid; 10034 offset4 offset; 10035 count4 count; 10036 }; 10038 struct READ4resok { 10039 bool eof; 10040 opaque data<>; 10041 }; 10043 union READ4res switch (nfsstat4 status) { 10044 case NFS4_OK: 10045 READ4resok resok4; 10046 default: 10047 void; 10048 }; 10050 /* 10051 * READDIR: Read directory 10052 */ 10053 struct READDIR4args { 10054 /* CURRENT_FH: directory */ 10055 nfs_cookie4 cookie; 10056 verifier4 cookieverf; 10058 Draft Specification NFS version 4 Protocol November 2001 10060 count4 dircount; 10061 count4 maxcount; 10062 bitmap4 attr_request; 10063 }; 10065 struct entry4 { 10066 nfs_cookie4 cookie; 10067 component4 name; 10068 fattr4 attrs; 10069 entry4 *nextentry; 10070 }; 10072 struct dirlist4 { 10073 entry4 *entries; 10074 bool eof; 10075 }; 10077 struct READDIR4resok { 10078 verifier4 cookieverf; 10079 dirlist4 reply; 10080 }; 10082 union READDIR4res switch (nfsstat4 status) { 10083 case NFS4_OK: 10084 READDIR4resok resok4; 10085 default: 10086 void; 10087 }; 10089 /* 10090 * READLINK: Read symbolic link 10091 */ 10092 struct READLINK4resok { 10093 linktext4 link; 10094 }; 10096 union READLINK4res switch (nfsstat4 status) { 10097 case NFS4_OK: 10098 READLINK4resok resok4; 10099 default: 10100 void; 10101 }; 10103 /* 10104 * REMOVE: Remove filesystem object 10105 */ 10106 struct REMOVE4args { 10107 /* CURRENT_FH: directory */ 10108 component4 target; 10109 }; 10111 Draft Specification NFS version 4 Protocol November 2001 10113 struct REMOVE4resok { 10114 change_info4 cinfo; 10115 }; 10117 union REMOVE4res switch (nfsstat4 status) { 10118 case NFS4_OK: 10119 REMOVE4resok resok4; 10120 default: 10121 void; 10122 }; 10124 /* 10125 * RENAME: Rename directory entry 10126 */ 10127 struct RENAME4args { 10128 /* SAVED_FH: source directory */ 10129 component4 oldname; 10130 /* CURRENT_FH: target directory */ 10131 component4 newname; 10132 }; 10134 struct RENAME4resok { 10135 change_info4 source_cinfo; 10136 change_info4 target_cinfo; 10137 }; 10139 union RENAME4res switch (nfsstat4 status) { 10140 case NFS4_OK: 10141 RENAME4resok resok4; 10142 default: 10143 void; 10144 }; 10146 /* 10147 * RENEW: Renew a Lease 10148 */ 10149 struct RENEW4args { 10150 clientid4 clientid; 10151 }; 10153 struct RENEW4res { 10154 nfsstat4 status; 10155 }; 10157 /* 10158 * RESTOREFH: Restore saved filehandle 10159 */ 10161 struct RESTOREFH4res { 10162 /* CURRENT_FH: value of saved fh */ 10163 nfsstat4 status; 10164 }; 10166 Draft Specification NFS version 4 Protocol November 2001 10168 /* 10169 * SAVEFH: Save current filehandle 10170 */ 10171 struct SAVEFH4res { 10172 /* SAVED_FH: value of current fh */ 10173 nfsstat4 status; 10174 }; 10176 /* 10177 * SECINFO: Obtain Available Security Mechanisms 10178 */ 10179 struct SECINFO4args { 10180 /* CURRENT_FH: directory */ 10181 component4 name; 10182 }; 10184 /* 10185 * From RFC 2203 10186 */ 10187 enum rpc_gss_svc_t { 10188 RPC_GSS_SVC_NONE = 1, 10189 RPC_GSS_SVC_INTEGRITY = 2, 10190 RPC_GSS_SVC_PRIVACY = 3 10191 }; 10193 struct rpcsec_gss_info { 10194 sec_oid4 oid; 10195 qop4 qop; 10196 rpc_gss_svc_t service; 10197 }; 10199 /* RPCSEC_GSS has a value of '6' - See RFC 2203 */ 10200 union secinfo4 switch (uint32_t flavor) { 10201 case RPCSEC_GSS: 10202 rpcsec_gss_info flavor_info; 10203 default: 10204 void; 10205 }; 10207 typedef secinfo4 SECINFO4resok<>; 10209 union SECINFO4res switch (nfsstat4 status) { 10210 case NFS4_OK: 10211 SECINFO4resok resok4; 10212 default: 10213 void; 10214 }; 10216 /* 10217 * SETATTR: Set attributes 10218 */ 10219 struct SETATTR4args { 10221 Draft Specification NFS version 4 Protocol November 2001 10223 /* CURRENT_FH: target object */ 10224 stateid4 stateid; 10225 fattr4 obj_attributes; 10226 }; 10228 struct SETATTR4res { 10229 nfsstat4 status; 10230 bitmap4 attrsset; 10231 }; 10233 /* 10234 * SETCLIENTID 10235 */ 10236 struct SETCLIENTID4args { 10237 nfs_client_id4 client; 10238 cb_client4 callback; 10239 }; 10241 struct SETCLIENTID4resok { 10242 clientid4 clientid; 10243 }; 10245 union SETCLIENTID4res switch (nfsstat4 status) { 10246 case NFS4_OK: 10247 SETCLIENTID4resok resok4; 10248 case NFS4ERR_CLID_INUSE: 10249 clientaddr4 client_using; 10250 default: 10251 void; 10252 }; 10254 struct SETCLIENTID_CONFIRM4args { 10255 clientid4 clientid; 10256 }; 10258 struct SETCLIENTID_CONFIRM4res { 10259 nfsstat4 status; 10260 }; 10262 /* 10263 * VERIFY: Verify attributes same 10264 */ 10265 struct VERIFY4args { 10266 /* CURRENT_FH: object */ 10267 fattr4 obj_attributes; 10268 }; 10270 struct VERIFY4res { 10271 nfsstat4 status; 10272 }; 10274 /* 10276 Draft Specification NFS version 4 Protocol November 2001 10278 * WRITE: Write to file 10279 */ 10280 enum stable_how4 { 10281 UNSTABLE4 = 0, 10282 DATA_SYNC4 = 1, 10283 FILE_SYNC4 = 2 10284 }; 10286 struct WRITE4args { 10287 /* CURRENT_FH: file */ 10288 stateid4 stateid; 10289 offset4 offset; 10290 stable_how4 stable; 10291 opaque data<>; 10292 }; 10294 struct WRITE4resok { 10295 count4 count; 10296 stable_how4 committed; 10297 verifier4 writeverf; 10298 }; 10300 union WRITE4res switch (nfsstat4 status) { 10301 case NFS4_OK: 10302 WRITE4resok resok4; 10303 default: 10304 void; 10305 }; 10307 /* 10308 * Operation arrays 10309 */ 10311 enum nfs_opnum4 { 10312 OP_ACCESS = 3, 10313 OP_CLOSE = 4, 10314 OP_COMMIT = 5, 10315 OP_CREATE = 6, 10316 OP_DELEGPURGE = 7, 10317 OP_DELEGRETURN = 8, 10318 OP_GETATTR = 9, 10319 OP_GETFH = 10, 10320 OP_LINK = 11, 10321 OP_LOCK = 12, 10322 OP_LOCKT = 13, 10323 OP_LOCKU = 14, 10324 OP_LOOKUP = 15, 10325 OP_LOOKUPP = 16, 10326 OP_NVERIFY = 17, 10327 OP_OPEN = 18, 10328 OP_OPENATTR = 19, 10329 OP_OPEN_CONFIRM = 20, 10331 Draft Specification NFS version 4 Protocol November 2001 10333 OP_OPEN_DOWNGRADE = 21, 10334 OP_PUTFH = 22, 10335 OP_PUTPUBFH = 23, 10336 OP_PUTROOTFH = 24, 10337 OP_READ = 25, 10338 OP_READDIR = 26, 10339 OP_READLINK = 27, 10340 OP_REMOVE = 28, 10341 OP_RENAME = 29, 10342 OP_RENEW = 30, 10343 OP_RESTOREFH = 31, 10344 OP_SAVEFH = 32, 10345 OP_SECINFO = 33, 10346 OP_SETATTR = 34, 10347 OP_SETCLIENTID = 35, 10348 OP_SETCLIENTID_CONFIRM = 36, 10349 OP_VERIFY = 37, 10350 OP_WRITE = 38 10351 }; 10353 union nfs_argop4 switch (nfs_opnum4 argop) { 10354 case OP_ACCESS: ACCESS4args opaccess; 10355 case OP_CLOSE: CLOSE4args opclose; 10356 case OP_COMMIT: COMMIT4args opcommit; 10357 case OP_CREATE: CREATE4args opcreate; 10358 case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; 10359 case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; 10360 case OP_GETATTR: GETATTR4args opgetattr; 10361 case OP_GETFH: void; 10362 case OP_LINK: LINK4args oplink; 10363 case OP_LOCK: LOCK4args oplock; 10364 case OP_LOCKT: LOCKT4args oplockt; 10365 case OP_LOCKU: LOCKU4args oplocku; 10366 case OP_LOOKUP: LOOKUP4args oplookup; 10367 case OP_LOOKUPP: void; 10368 case OP_NVERIFY: NVERIFY4args opnverify; 10369 case OP_OPEN: OPEN4args opopen; 10370 case OP_OPENATTR: OPENATTR4args opopenattr; 10371 case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; 10372 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4args opopen_downgrade; 10373 case OP_PUTFH: PUTFH4args opputfh; 10374 case OP_PUTPUBFH: void; 10375 case OP_PUTROOTFH: void; 10376 case OP_READ: READ4args opread; 10377 case OP_READDIR: READDIR4args opreaddir; 10378 case OP_READLINK: void; 10379 case OP_REMOVE: REMOVE4args opremove; 10380 case OP_RENAME: RENAME4args oprename; 10381 case OP_RENEW: RENEW4args oprenew; 10382 case OP_RESTOREFH: void; 10383 case OP_SAVEFH: void; 10384 case OP_SECINFO: SECINFO4args opsecinfo; 10386 Draft Specification NFS version 4 Protocol November 2001 10388 case OP_SETATTR: SETATTR4args opsetattr; 10389 case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; 10390 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args 10391 opsetclientid_confirm; 10392 case OP_VERIFY: VERIFY4args opverify; 10393 case OP_WRITE: WRITE4args opwrite; 10394 }; 10396 union nfs_resop4 switch (nfs_opnum4 resop){ 10397 case OP_ACCESS: ACCESS4res opaccess; 10398 case OP_CLOSE: CLOSE4res opclose; 10399 case OP_COMMIT: COMMIT4res opcommit; 10400 case OP_CREATE: CREATE4res opcreate; 10401 case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; 10402 case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; 10403 case OP_GETATTR: GETATTR4res opgetattr; 10404 case OP_GETFH: GETFH4res opgetfh; 10405 case OP_LINK: LINK4res oplink; 10406 case OP_LOCK: LOCK4res oplock; 10407 case OP_LOCKT: LOCKT4res oplockt; 10408 case OP_LOCKU: LOCKU4res oplocku; 10409 case OP_LOOKUP: LOOKUP4res oplookup; 10410 case OP_LOOKUPP: LOOKUPP4res oplookupp; 10411 case OP_NVERIFY: NVERIFY4res opnverify; 10412 case OP_OPEN: OPEN4res opopen; 10413 case OP_OPENATTR: OPENATTR4res opopenattr; 10414 case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; 10415 case OP_OPEN_DOWNGRADE: OPEN_DOWNGRADE4res opopen_downgrade; 10416 case OP_PUTFH: PUTFH4res opputfh; 10417 case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; 10418 case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; 10419 case OP_READ: READ4res opread; 10420 case OP_READDIR: READDIR4res opreaddir; 10421 case OP_READLINK: READLINK4res opreadlink; 10422 case OP_REMOVE: REMOVE4res opremove; 10423 case OP_RENAME: RENAME4res oprename; 10424 case OP_RENEW: RENEW4res oprenew; 10425 case OP_RESTOREFH: RESTOREFH4res oprestorefh; 10426 case OP_SAVEFH: SAVEFH4res opsavefh; 10427 case OP_SECINFO: SECINFO4res opsecinfo; 10428 case OP_SETATTR: SETATTR4res opsetattr; 10429 case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; 10430 case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4res 10431 opsetclientid_confirm; 10432 case OP_VERIFY: VERIFY4res opverify; 10433 case OP_WRITE: WRITE4res opwrite; 10434 }; 10436 struct COMPOUND4args { 10437 utf8string tag; 10438 uint32_t minorversion; 10439 nfs_argop4 argarray<>; 10441 Draft Specification NFS version 4 Protocol November 2001 10443 }; 10445 struct COMPOUND4res { 10446 nfsstat4 status; 10447 utf8string tag; 10448 nfs_resop4 resarray<>; 10449 }; 10451 /* 10452 * Remote file service routines 10453 */ 10454 program NFS4_PROGRAM { 10455 version NFS_V4 { 10456 void 10457 NFSPROC4_NULL(void) = 0; 10459 COMPOUND4res 10460 NFSPROC4_COMPOUND(COMPOUND4args) = 1; 10462 } = 4; 10463 } = 100003; 10465 /* 10466 * NFS4 Callback Procedure Definitions and Program 10467 */ 10469 /* 10470 * CB_GETATTR: Get Current Attributes 10471 */ 10472 struct CB_GETATTR4args { 10473 nfs_fh4 fh; 10474 bitmap4 attr_request; 10475 }; 10477 struct CB_GETATTR4resok { 10478 fattr4 obj_attributes; 10479 }; 10481 union CB_GETATTR4res switch (nfsstat4 status) { 10482 case NFS4_OK: 10483 CB_GETATTR4resok resok4; 10484 default: 10485 void; 10486 }; 10488 /* 10489 * CB_RECALL: Recall an Open Delegation 10490 */ 10491 struct CB_RECALL4args { 10492 stateid4 stateid; 10494 Draft Specification NFS version 4 Protocol November 2001 10496 bool truncate; 10497 nfs_fh4 fh; 10498 }; 10500 struct CB_RECALL4res { 10501 nfsstat4 status; 10502 }; 10504 /* 10505 * Various definitions for CB_COMPOUND 10506 */ 10507 enum nfs_cb_opnum4 { 10508 OP_CB_GETATTR = 3, 10509 OP_CB_RECALL = 4 10510 }; 10512 union nfs_cb_argop4 switch (unsigned argop) { 10513 case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr; 10514 case OP_CB_RECALL: CB_RECALL4args opcbrecall; 10515 }; 10517 union nfs_cb_resop4 switch (unsigned resop){ 10518 case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; 10519 case OP_CB_RECALL: CB_RECALL4res opcbrecall; 10520 }; 10522 struct CB_COMPOUND4args { 10523 utf8string tag; 10524 uint32_t minorversion; 10525 nfs_cb_argop4 argarray<>; 10526 }; 10528 struct CB_COMPOUND4res { 10529 nfsstat4 status; 10530 utf8string tag; 10531 nfs_cb_resop4 resarray<>; 10532 }; 10534 /* 10535 * Program number is in the transient range since the client 10536 * will assign the exact transient program number and provide 10537 * that to the server via the SETCLIENTID operation. 10538 */ 10539 program NFS4_CALLBACK { 10540 version NFS_CB { 10541 void 10542 CB_NULL(void) = 0; 10543 CB_COMPOUND4res 10544 CB_COMPOUND(CB_COMPOUND4args) = 1; 10545 } = 1; 10546 } = 0x40000000; 10548 Draft Specification NFS version 4 Protocol November 2001 10550 19. Bibliography 10552 [Floyd] 10553 S. Floyd, V. Jacobson, "The Synchronization of Periodic Routing 10554 Messages," IEEE/ACM Transactions on Networking, 2(2), pp. 122-136, 10555 April 1994. 10557 [Gray] 10558 C. Gray, D. Cheriton, "Leases: An Efficient Fault-Tolerant Mechanism 10559 for Distributed File Cache Consistency," Proceedings of the Twelfth 10560 Symposium on Operating Systems Principles, p. 202-210, December 1989. 10562 [ISO10646] 10563 "ISO/IEC 10646-1:1993. International Standard -- Information 10564 technology -- Universal Multiple-Octet Coded Character Set (UCS) -- 10565 Part 1: Architecture and Basic Multilingual Plane." 10567 [Juszczak] 10568 Juszczak, Chet, "Improving the Performance and Correctness of an NFS 10569 Server," USENIX Conference Proceedings, USENIX Association, Berkeley, 10570 CA, June 1990, pages 53-63. Describes reply cache implementation 10571 that avoids work in the server by handling duplicate requests. More 10572 important, though listed as a side-effect, the reply cache aids in 10573 the avoidance of destructive non-idempotent operation re-application 10574 -- improving correctness. 10576 [Kazar] 10577 Kazar, Michael Leon, "Synchronization and Caching Issues in the 10578 Andrew File System," USENIX Conference Proceedings, USENIX 10579 Association, Berkeley, CA, Dallas Winter 1988, pages 27-36. A 10580 description of the cache consistency scheme in AFS. Contrasted with 10581 other distributed file systems. 10583 [Macklem] 10584 Macklem, Rick, "Lessons Learned Tuning the 4.3BSD Reno Implementation 10585 of the NFS Protocol," Winter USENIX Conference Proceedings, USENIX 10586 Association, Berkeley, CA, January 1991. Describes performance work 10587 in tuning the 4.3BSD Reno NFS implementation. Describes performance 10588 improvement (reduced CPU loading) through elimination of data copies. 10590 [Mogul] 10591 Mogul, Jeffrey C., "A Recovery Protocol for Spritely NFS," USENIX 10592 File System Workshop Proceedings, Ann Arbor, MI, USENIX Association, 10593 Berkeley, CA, May 1992. Second paper on Spritely NFS proposes a 10594 lease-based scheme for recovering state of consistency protocol. 10596 Draft Specification NFS version 4 Protocol November 2001 10598 [Nowicki] 10599 Nowicki, Bill, "Transport Issues in the Network File System," ACM 10600 SIGCOMM newsletter Computer Communication Review, April 1989. A 10601 brief description of the basis for the dynamic retransmission work. 10603 [Pawlowski] 10604 Pawlowski, Brian, Ron Hixon, Mark Stein, Joseph Tumminaro, "Network 10605 Computing in the UNIX and IBM Mainframe Environment," Uniforum `89 10606 Conf. Proc., (1989) Description of an NFS server implementation for 10607 IBM's MVS operating system. 10609 [RFC1094] 10610 Sun Microsystems, Inc., "NFS: Network File System Protocol 10611 Specification", RFC1094, March 1989. 10613 http://www.ietf.org/rfc/rfc1094.txt 10615 [RFC1345] 10616 Simonsen, K., "Character Mnemonics & Character Sets", RFC1345, 10617 Rationel Almen Planlaegning, June 1992. 10619 http://www.ietf.org/rfc/rfc1345.txt 10621 [RFC1700] 10622 Reynolds, J., Postel, J., "Assigned Numbers", RFC1700, ISI, October 10623 1994 10625 http://www.ietf.org/rfc/rfc1700.txt 10627 [RFC1813] 10628 Callaghan, B., Pawlowski, B., Staubach, P., "NFS Version 3 Protocol 10629 Specification", RFC1813, Sun Microsystems, Inc., June 1995. 10631 http://www.ietf.org/rfc/rfc1813.txt 10633 [RFC1831] 10634 Srinivasan, R., "RPC: Remote Procedure Call Protocol Specification 10635 Version 2", RFC1831, Sun Microsystems, Inc., August 1995. 10637 http://www.ietf.org/rfc/rfc1831.txt 10639 [RFC1832] 10640 Srinivasan, R., "XDR: External Data Representation Standard", 10641 RFC1832, Sun Microsystems, Inc., August 1995. 10643 Draft Specification NFS version 4 Protocol November 2001 10645 http://www.ietf.org/rfc/rfc1832.txt 10647 [RFC1833] 10648 Srinivasan, R., "Binding Protocols for ONC RPC Version 2", RFC1833, 10649 Sun Microsystems, Inc., August 1995. 10651 http://www.ietf.org/rfc/rfc1833.txt 10653 [RFC2025] 10654 Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", RFC2025, 10655 Bell-Northern Research, October 1996. 10657 http://www.ietf.org/rfc/rfc2026.txt 10659 [RFC2054] 10660 Callaghan, B., "WebNFS Client Specification", RFC2054, Sun 10661 Microsystems, Inc., October 1996 10663 http://www.ietf.org/rfc/rfc2054.txt 10665 [RFC2055] 10666 Callaghan, B., "WebNFS Server Specification", RFC2055, Sun 10667 Microsystems, Inc., October 1996 10669 http://www.ietf.org/rfc/rfc2055.txt 10671 [RFC2078] 10672 Linn, J., "Generic Security Service Application Program Interface, 10673 Version 2", RFC2078, OpenVision Technologies, January 1997. 10675 http://www.ietf.org/rfc/rfc2078.txt 10677 [RFC2152] 10678 Goldsmith, D., "UTF-7 A Mail-Safe Transformation Format of Unicode", 10679 RFC2152, Apple Computer, Inc., May 1997 10681 http://www.ietf.org/rfc/rfc2152.txt 10683 [RFC2203] 10684 Eisler, M., Chiu, A., Ling, L., "RPCSEC_GSS Protocol Specification", 10685 RFC2203, Sun Microsystems, Inc., August 1995. 10687 http://www.ietf.org/rfc/rfc2203.txt 10689 Draft Specification NFS version 4 Protocol November 2001 10691 [RFC2277] 10692 Alvestrand, H., "IETF Policy on Character Sets and Languages", 10693 RFC2277, UNINETT, January 1998. 10695 http://www.ietf.org/rfc/rfc2277.txt 10697 [RFC2279] 10698 Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC2279, 10699 Alis Technologies, January 1998. 10701 http://www.ietf.org/rfc/rfc2279.txt 10703 [RFC2623] 10704 Eisler, M., "NFS Version 2 and Version 3 Security Issues and the NFS 10705 Protocol's Use of RPCSEC_GSS and Kerberos V5", RFC2623, Sun 10706 Microsystems, June 1999 10708 http://www.ietf.org/rfc/rfc2623.txt 10710 [RFC2624] 10711 Shepler, S., "NFS Version 4 Design Considerations", RFC2624, Sun 10712 Microsystems, June 1999 10714 http://www.ietf.org/rfc/rfc2624.txt 10716 [RFC2847] 10717 Eisler, M., "LIPKEY - A Low Infrastructure Public Key Mechanism Using 10718 SPKM", RFC2847, Sun Microsystems, June 2000 10720 http://www.ietf.org/internet-drafts/draft-ietf-cat-lipkey-03.txt 10722 [Sandberg] 10723 Sandberg, R., D. Goldberg, S. Kleiman, D. Walsh, B. Lyon, "Design 10724 and Implementation of the Sun Network Filesystem," USENIX Conference 10725 Proceedings, USENIX Association, Berkeley, CA, Summer 1985. The 10726 basic paper describing the SunOS implementation of the NFS version 2 10727 protocol, and discusses the goals, protocol specification and trade- 10728 offs. 10730 [Srinivasan] 10731 Srinivasan, V., Jeffrey C. Mogul, "Spritely NFS: Implementation and 10732 Performance of Cache Consistency Protocols", WRL Research Report 10733 89/5, Digital Equipment Corporation Western Research Laboratory, 100 10734 Hamilton Ave., Palo Alto, CA, 94301, May 1989. This paper analyzes 10735 the effect of applying a Sprite-like consistency protocol applied to 10736 standard NFS. The issues of recovery in a stateful environment are 10738 Draft Specification NFS version 4 Protocol November 2001 10740 covered in [Mogul]. 10742 [Unicode1] 10743 The Unicode Consortium, "The Unicode Standard, Version 3.0", 10744 Addison-Wesley Developers Press, Reading, MA, 2000. ISBN 0-201- 10745 61633-5. 10747 More information available at: http://www.unicode.org/ 10749 [Unicode2] 10750 "Unsupported Scripts" Unicode, Inc., The Unicode Consortium, P.O. Box 10751 700519, San Jose, CA 95710-0519 USA, September 1999 10753 http://www.unicode.org/unicode/standard/unsupported.html 10755 [XNFS] 10756 The Open Group, Protocols for Interworking: XNFS, Version 3W, The 10757 Open Group, 1010 El Camino Real Suite 380, Menlo Park, CA 94025, ISBN 10758 1-85912-184-5, February 1998. 10760 HTML version available: http://www.opengroup.org 10762 Draft Specification NFS version 4 Protocol November 2001 10764 20. Authors 10766 20.1. Editor's Address 10768 Spencer Shepler 10769 Sun Microsystems, Inc. 10770 7808 Moonflower Drive 10771 Austin, Texas 78750 10773 Phone: +1 512-349-9376 10774 E-mail: spencer.shepler@sun.com 10776 20.2. Authors' Addresses 10778 Carl Beame 10779 Hummingbird Ltd. 10781 E-mail: beame@bws.com 10783 Brent Callaghan 10784 Sun Microsystems, Inc. 10785 901 San Antonio Road 10786 Palo Alto, CA 94303 10788 Phone: +1 650-786-5067 10789 E-mail: brent.callaghan@sun.com 10791 Mike Eisler 10792 5565 Wilson Road 10793 Colorado Springs, CO 80919 10795 Phone: +1 719-599-9026 10796 E-mail: mike@eisler.com 10798 David Noveck 10799 Network Appliance 10800 375 Totten Pond Road 10801 Waltham, MA 02451 10803 Phone: +1 781-895-4949 10804 E-mail: dnoveck@netapp.com 10806 David Robinson 10807 Sun Microsystems, Inc. 10808 901 San Antonio Road 10809 Palo Alto, CA 94303 10811 Draft Specification NFS version 4 Protocol November 2001 10813 Phone: +1 650-786-5088 10814 E-mail: david.robinson@sun.com 10816 Robert Thurlow 10817 Sun Microsystems, Inc. 10818 901 San Antonio Road 10819 Palo Alto, CA 94303 10821 Phone: +1 650-786-5096 10822 E-mail: robert.thurlow@sun.com 10824 20.3. Acknowledgements 10826 The author thanks and acknowledges: 10828 Neil Brown for his extensive review and comments of various drafts. 10830 Draft Specification NFS version 4 Protocol November 2001 10832 21. Full Copyright Statement 10834 "Copyright (C) The Internet Society (2000,2001). 10835 All Rights Reserved. 10837 This document and translations of it may be copied and furnished to 10838 others, and derivative works that comment on or otherwise explain it 10839 or assist in its implementation may be prepared, copied, published 10840 and distributed, in whole or in part, without restriction of any 10841 kind, provided that the above copyright notice and this paragraph are 10842 included on all such copies and derivative works. However, this 10843 document itself may not be modified in any way, such as by removing 10844 the copyright notice or references to the Internet Society or other 10845 Internet organizations, except as needed for the purpose of 10846 developing Internet standards in which case the procedures for 10847 copyrights defined in the Internet Standards process must be 10848 followed, or as required to translate it into languages other than 10849 English. 10851 The limited permissions granted above are perpetual and will not be 10852 revoked by the Internet Society or its successors or assigns. 10854 This document and the information contained herein is provided on an 10855 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 10856 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 10857 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 10858 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 10859 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."