--- 1/draft-ietf-nfsv4-rfc3530bis-29.txt 2014-01-09 14:14:37.041261984 -0800 +++ 2/draft-ietf-nfsv4-rfc3530bis-30.txt 2014-01-09 14:14:37.585275009 -0800 @@ -1,19 +1,19 @@ NFSv4 T. Haynes, Ed. Internet-Draft NetApp Obsoletes: 3530 (if approved) D. Noveck, Ed. Intended status: Standards Track EMC -Expires: June 1, 2014 November 28, 2013 +Expires: July 13, 2014 January 09, 2014 Network File System (NFS) Version 4 Protocol - draft-ietf-nfsv4-rfc3530bis-29.txt + draft-ietf-nfsv4-rfc3530bis-30.txt Abstract The Network File System (NFS) version 4 is a distributed file system protocol which builds on the heritage of NFS protocol version 2, RFC 1094, and version 3, RFC 1813. Unlike earlier versions, the NFS version 4 protocol supports traditional file access while integrating support for file locking and the mount protocol. In addition, support for strong security (and its negotiation), compound operations, client caching, and internationalization have been added. @@ -38,25 +38,25 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on June 1, 2014. + This Internet-Draft will expire on July 13, 2014. Copyright Notice - Copyright (c) 2013 IETF Trust and the persons identified as the + Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as @@ -221,111 +221,111 @@ 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 159 10.7. Data and Metadata Caching and Memory Mapped Files . . . 161 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 163 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 164 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 165 12. Internationalization . . . . . . . . . . . . . . . . . . . . 168 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 168 12.2. Limitations on internationalization-related processing in the NFSv4 context . . . . . . . . . . . . 169 - 12.3. String Encoding . . . . . . . . . . . . . . . . . . . . 169 - 12.4. Normalization . . . . . . . . . . . . . . . . . . . . . 170 - 12.5. Types with Processing Defined by Other Internet Areas . 171 - 12.6. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 172 - 12.7. Handling of component names that are not valid UTF-8 - strings . . . . . . . . . . . . . . . . . . . . . . . . 172 - 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 173 - 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 174 - 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 175 - 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 176 - 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 178 - 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 179 - 13.1.5. State Management Errors . . . . . . . . . . . . . . 181 - 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 182 - 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 182 - 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 183 - 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 184 - 13.1.10. Client Management Errors . . . . . . . . . . . . . . 185 - 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 185 - 13.2. Operations and their valid errors . . . . . . . . . . . 186 - 13.3. Callback operations and their valid errors . . . . . . . 193 - 13.4. Errors and the operations that use them . . . . . . . . 194 - 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 198 - 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 199 - 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 199 - 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 200 - 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 200 - 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 201 - 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 201 - 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 201 - 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 205 - 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 208 - 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 209 - 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 211 + 12.3. Summary of Server Behavior Types . . . . . . . . . . . . 170 + 12.4. String Encoding . . . . . . . . . . . . . . . . . . . . 171 + 12.5. Normalization . . . . . . . . . . . . . . . . . . . . . 171 + 12.6. Types with Processing Defined by Other Internet Areas . 172 + 12.7. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 173 + 12.8. Servers that accept file component names that are not + valid UTF-8 strings . . . . . . . . . . . . . . . . . . 174 + 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 175 + 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 175 + 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 177 + 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 178 + 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 179 + 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 180 + 13.1.5. State Management Errors . . . . . . . . . . . . . . 182 + 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 183 + 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 184 + 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 184 + 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 186 + 13.1.10. Client Management Errors . . . . . . . . . . . . . . 186 + 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 187 + 13.2. Operations and their valid errors . . . . . . . . . . . 187 + 13.3. Callback operations and their valid errors . . . . . . . 194 + 13.4. Errors and the operations that use them . . . . . . . . 195 + 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 199 + 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 200 + 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 200 + 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 201 + 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 201 + 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 202 + 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 202 + 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 202 + 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 206 + 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 209 + 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 210 + 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 212 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting - Recovery . . . . . . . . . . . . . . . . . . . . . . . . 214 - 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 215 - 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 216 - 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 218 - 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 219 - 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 220 - 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 224 - 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 226 - 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 227 - 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 229 + Recovery . . . . . . . . . . . . . . . . . . . . . . . . 215 + 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 216 + 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 217 + 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 219 + 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 220 + 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 221 + 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 225 + 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 227 + 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 228 + 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 230 15.17. Operation 17: NVERIFY - Verify Difference in - Attributes . . . . . . . . . . . . . . . . . . . . . . . 230 - 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 231 + Attributes . . . . . . . . . . . . . . . . . . . . . . . 231 + 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 232 15.19. Operation 19: OPENATTR - Open Named Attribute - Directory . . . . . . . . . . . . . . . . . . . . . . . 241 - 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 242 - 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 244 - 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 245 - 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 246 - 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 247 - 15.25. Operation 25: READ - Read from File . . . . . . . . . . 248 - 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 250 - 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 254 - 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 255 - 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 257 - 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 259 - 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 260 - 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 261 - 15.33. Operation 33: SECINFO - Obtain Available Security . . . 262 - 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 266 - 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 268 - 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 272 - 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 275 - 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 277 + Directory . . . . . . . . . . . . . . . . . . . . . . . 242 + 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 243 + 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 245 + 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 246 + 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 247 + 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 248 + 15.25. Operation 25: READ - Read from File . . . . . . . . . . 249 + 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 251 + 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 255 + 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 256 + 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 258 + 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 260 + 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 261 + 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 262 + 15.33. Operation 33: SECINFO - Obtain Available Security . . . 263 + 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 267 + 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 269 + 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 273 + 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 276 + 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 278 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner - State . . . . . . . . . . . . . . . . . . . . . . . . . 281 - 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 282 - 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 283 - 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 283 - 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 283 - 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 285 - 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 286 + State . . . . . . . . . . . . . . . . . . . . . . . . . 282 + 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 283 + 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 284 + 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 284 + 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 284 + 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 286 + 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 287 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback - Operation . . . . . . . . . . . . . . . . . . . . . 287 - 17. Security Considerations . . . . . . . . . . . . . . . . . . . 288 - 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 290 - 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 290 - 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 291 - 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 291 - 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 291 - 19.1. Normative References . . . . . . . . . . . . . . . . . . 291 - 19.2. Informative References . . . . . . . . . . . . . . . . . 292 - - Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 295 - Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 296 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 296 + Operation . . . . . . . . . . . . . . . . . . . . . 288 + 17. Security Considerations . . . . . . . . . . . . . . . . . . . 289 + 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 291 + 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 291 + 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 292 + 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 292 + 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 292 + 19.1. Normative References . . . . . . . . . . . . . . . . . . 292 + 19.2. Informative References . . . . . . . . . . . . . . . . . 293 + Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 296 + Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 297 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 297 1. Introduction 1.1. NFS Version 4 Goals The Network Filesystem version 4 (NFSv4) protocol is a further revision of the NFS protocol defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains the essential characteristics of previous versions: design for easy recovery, independent of transport protocols, operating systems and file systems, simplicity, and good @@ -2315,21 +2315,21 @@ As mentioned above, it is desirable that a server when accepting a string of the form user@domain or group@domain in an attribute, return this same string when that corresponding attribute is fetched. Internationalization issues (for a general discussion of which see Section 12) may make this impossible and the client needs to take note of the following situations: o The string representing the domain may be converted to equivalent U-label (see [RFC5890]), if presented using a form other than a - U-label. See Section 12.5 for details. + U-label. See Section 12.6 for details. o The user or group may be returned in a different form, due to normalization issues, although it will always be a canonically equivalent string. In the case where there is no translation available to the client or server, the attribute value will be constructed without the "@". Therefore, the absence of the "@" from the owner or owner_group attribute signifies that no translation was available at the sender and that the receiver of the attribute should not use that string as @@ -5722,23 +5722,23 @@ some information in stable storage. The amount of information the server records in stable storage is in inverse proportion to how harsh the server wants to be whenever the edge conditions occur. The server that is completely tolerant of all edge conditions will record in stable storage every lock that is acquired, removing the lock record from stable storage only when the lock is unlocked by the client and the lock's owner advances the sequence number such that the lock release is not the last stateful event for the owner's sequence. For the two aforementioned edge conditions, the harshest a server can be, and still support a grace period for reclaims, - requires that the server record in stable storage information some - minimal information. For example, a server implementation could, for - each client, save in stable storage a record containing: + requires that the server record in stable storage some minimal + information. For example, a server implementation could, for each + client, save in stable storage a record containing: o the client's id string o a boolean that indicates if the client's lease expired or if there was administrative intervention (see Section 9.8) to revoke a byte-range lock, share reservation, or delegation o a timestamp that is updated the first time after a server boot or reboot the client acquires byte-range locking, share reservation, or delegation state on the server. The timestamp need not be @@ -7856,25 +7856,34 @@ 12.1. Introduction This section uses NFSv4.0 internationalization, as implemented by existing clients and servers, as the basis upon which NFSv4.0 clients may implement internationalization support. This procedure, while necessary, may result in confusion if we do not clearly understand that we are mixing prescription and description, and why, in this particular case, this is a valid thing to do. - Note that in this chapter, the keywords "MUST", "SHOULD", and "MAY", + This section is based on the behavior of existing implementations. + Note that the behaviors described are each demonstrated by a + combination of an NFSv4 server implementation proper and a server- + side physical filesystem. It is common for servers and physical + filesystems to be configurable as to the behavior shown once set up + and each be configuration showing different behavior is considered + separately, for our purposes. + + Note that in this section, the keywords "MUST", "SHOULD", and "MAY", retain their normal meanings. However, in deriving this specification from implementation patterns, we document below how the normative terms used derive from the behavior of existing - implementations. + implementations, in those situations in which existing implementation + behavior patterns can be determined. o Behavior implemented by all existing clients or servers is described using "MUST", since new implementations need to follow existing ones to be assured of interoperability. While it is possible that different behavior might be workable, we have found no case where this seems reasonable. o Behavior implemented by no existing clients or servers is described using "MUST NOT", if such behavior poses interoperability problems. @@ -7892,20 +7901,44 @@ implementations will have the same flexibility that existing ones do. o Behavior implemented by all existing clients or servers, so far as is known, but where there remains some uncertainty as to details is described using "should". Such cases primarily concern details of error returns. New implementations should follow existing practice even though such situations generally do not affect interoperability. + There are also cases in which certain server behaviors, while not + known to exist, cannot be reliably determined not to exist. In part, + this is a consequence of the long period of time that has elapsed + since the publication of [RFC3530], resulting in a situation in which + those involved in the implementation may no longer be involved in or + aware of working group activities. + + In the case of possible server behavior that is neither known to + exist nor known not to exist, we use SHOULD NOT and MUST NOT as + follows, and similarly for "SHOULD" and "MUST". + + o In some cases, the potential behavior is not known to exist but is + of such a nature that, if it were in fact implemented, + interoperability difficulties would be expected and reported, + giving us cause to conclude that the potential behavior is not + implemented. For such behavior, we use MUST NOT. Similarly we + use "MUST" to apply to the contrary behavior. + + o In other cases, potential behavior is not known to exist but the + behavior, while undesirable, is not of such a nature that we are + able to draw any conclusions about its potential existence. In + such cases, we use SHOULD NOT. Similarly we use "SHOULD" to apply + to the contrary behavior. + In the case of a MAY, SHOULD, or SHOULD NOT that applies to servers, clients need to be aware that there are servers which may or may not take the specified action, and they need to be prepared for either eventuality. 12.2. Limitations on internationalization-related processing in the NFSv4 context There are a number of noteworthy circumstances that limit the degree to which internationalization-related processing can be made @@ -7923,62 +7956,95 @@ o Typical implementation patterns in Unix systems may mean that the NFSv4 client has no knowledge of the character encoding being used, which may even vary between processes on the same client system. o Users may need access to files stored previously with non-UTF-8 encodings, or with UTF-8 encodings that do not match any particular normalization form. -12.3. String Encoding +12.3. Summary of Server Behavior Types + + As mentioned in Section 12.6, servers MAY reject component name + strings that are not valid UTF-8. This leads to a number of types of + valid server behavior as outlined below. When these are combined + with the valid normalization-related behaviors as described in + Section 12.4, this leads to the combined behaviors outlined below. + + o Servers which do limit file component names to UTF-8 strings exist + with all of the forms of normalization-related handling described + in Section 12.4. These are best described as "UTF-8-only + servers". + + o Servers which do not limit file component names to UTF-8 strings + are very common and are necessary to deal with clients/ + applications not oriented to the use of UTF-8. Such servers + ignore normalization-related issues and there is no way for them + to implement either normalization or representation-independent + lookups. These are best described as "UTF-8-unaware servers" + since they treat file component names as uninterpreted strings of + bytes and have no knowledge of the characters represented. Such + servers ignore normalization-related issues and there is no way + for them to implement either normalization or representation- + independent lookups. See Section 12.7 for details. + + o It is possible for a server to allow component names which are not + valid UTF-8, while still being aware of the structure of UTF-8 + strings. Such servers could implement either normalization or + representation-independent lookups, but apply those techniques + only to valid UTF-8 strings. Such servers are not known to exist + and SHOULD NOT be implemented because of the possibility that a + filename using one character set may, by accident, have the + appearance of a UTF-8 filename. See Section 12.7 for details. + +12.4. String Encoding Strings that potentially contain non-ASCII Characters are generally represented in NFSv4 using the UTF-8 encoding of Unicode. See [RFC2279] for precise encoding and decoding rules. Some details of the protocol treatment depend on the type of string: o For strings which are component names, the preferred encoding for - any non-ASCII characters is any non-ASCII characters is the UTF-8 - representation of Unicode. + any non-ASCII characters is the UTF-8 representation of Unicode. In many cases, clients have no knowledge of the encoding being used, with the encoding done at user-level under control of a per- process locale specification. As a result, it may be impossible for the NFSv4 client to enforce use of UTF-8. Use of non-UTF-8 encodings can be problematic since it may interfere with access to files stored using other forms of name encoding. Also, - normalization-related processing (see Section 12.4) of a string + normalization-related processing (see Section 12.5) of a string not encoded in UTF-8 could result in inappropriate name modification or aliasing. In cases in which one has a non-UT8- name that accidentally conforms to UTF-8 rules, substitution of canonically equivalent strings can change the non-UTF-8 encoded name drastically. o For strings whose form is defined by other internet standards, non-ASCII characters MUST be represented using the UTF-8 encoding of Unicode. In addition other sorts of restrictions defined by - those standards need to be addressed. See Section 12.5 for + those standards need to be addressed. See Section 12.6 for details. o The contents of symbolic links (of type linktext4 in the XDR) MUST be treated as opaque data by NFSv4 servers. Although UTF-8 encoding is often used, it need not be. In this respect, the contents of symbolic links are like the contents of regular files in that their encoding is not within the scope of this specification. o For other sorts of strings, any non-ASCII characters SHOULD be represented using the UTF-8 encoding of Unicode. -12.4. Normalization +12.5. Normalization The client and server operating environments may differ in their policies and operational methods with respect to character normalization (See [Unicode1] for a discussion of normalization forms). This difference may also exist between applications on the same client. This adds to the difficulty of providing a single normalization policy for the protocol that allows for maximal interoperability. This issue is similar to the character case issues where the server may or may not support case insensitive file name matching and may or may not preserve the character case when storing @@ -7998,24 +8064,24 @@ Server implementations MAY normalize file names to conform to a particular normalization form before using the resulting string when looking up or creating a file. Servers MAY also perform normalization-insensitive string comparisons without modifying name to match a particular normalization form. Except in cases in which component names are excluded from normalization-related handling because they are not valid UTF-8 strings, a server MUST make the same choice (as to whether to normalize or not, the target form of normalization and whether to do normalization-insensitive string comparisons) in the same way for all accesses to a particular - filesystem. Servers MUST NOT reject a file name because it doesn't a + filesystem. Servers MUST NOT reject a file name because it does not conform to a particular normalization form. -12.5. Types with Processing Defined by Other Internet Areas +12.6. Types with Processing Defined by Other Internet Areas There are two types of strings which NFSv4 deals with whose processing is defined by other Internet standards, and where issues related to different handling choices by server operating systems or server file systems do not apply. These are as follows: o Server names as they appear in the fs_locations attribute. Note that for most purposes, such server names will only be sent by the @@ -8050,93 +8116,93 @@ server does not map domain strings which are not U-labels into a U-label, which it MAY do, it MUST NOT modify the domain, and the domain returned on a GETATTR of the userid MUST be the same as that used when setting the userid by the SETATTR. The server MAY implement VERIFY and NVERIFY without translating internal state to a string form, so that, for example, a user principal which represents a specific numeric user id, will match a different principal string which represents the same numeric user id. -12.6. UTF-8 Related Errors +12.7. UTF-8 Related Errors Where the client sends an invalid UTF-8 string, the server MAY return an NFS4ERR_INVAL error. This includes cases in which inappropriate prefixes are detected and where the count includes trailing bytes that do not constitute a full UCS character. Requirements for server handling of component names which are not valid UTF-8, when a server does not return NFS4ERR_INVAL in response - to receiving them, are described in Section 12.7. + to receiving them, are described in Section 12.8. Where the client supplied string is not rejected with NFS4ERR_INVAL but contains characters that are not supported by the server as a value for that string (e.g., names containing slashes, or characters that have more than two octets on a filesystem that supports Unicode characters only), the server should return an NFS4ERR_BADCHAR error. Where a UTF-8 string is used as a file name, and the file system, while supporting all of the characters within the name, does not allow that particular name to be used, the error should return the error NFS4ERR_BADNAME. This includes such situations as file system prohibitions of "." and ".." as file names for certain operations, and similar constraints -12.7. Handling of component names that are not valid UTF-8 strings - - In cases in which the server receives a component name that is not a - valid UTF-8 string, the required handling depends on whether a file - object is being created or looked up. Object creation happens for - the component name in LINK and CREATE, and the second component name - in RENAME. Object lookup happens for the component name in LOOKUP - and REMOVE, and the first component name in RENAME. The component - name in OPEN will result in object lookup and also object creation if - the lookup fails and the other OPEN parameters allow file creation. - - With regard to normalization-related processing, it is generally - inhibited, both in the case of object creation and object lookup: - - o Characters which are not valid UTF-8 have no canonically - equivalent Unicode string, so normalization-related processing - cannot happen. - - o In cases in which a string has valid UTF-8 character strings that - do have canonically equivalent Unicode strings, but if the - component name is not valid UTF-8, the server MAY perform - normalization-related processing on valid UTF-8 substrings within - it that do have canonical equivalents. +12.8. Servers that accept file component names that are not valid UTF-8 + strings - When creation of a component name which is not valid UTF-8 occurs, - and is allowed by the server: + As stated previously, servers MAY accept, on all or on some subset of + the physical filesystems exported, component names that are not valid + UTF-8 strings. A typical pattern is for a server to use UTF-8- + unaware physical filesystems that treat component names as + uninterpreted strings of bytes, rather than having any awareness of + the character set being used. - o A subsequent lookup of the same component name in the same - directory MUST result in finding the created file object. + Such servers SHOULD NOT change the stored representation of component + names from those received on the wire, and SHOULD use binary + comparison of component name strings to determine equivalence (as + opposed to any broader notion of string comparison). This is because + the server has no knowledge of the character encoding being used. - o A READDIR of the directory in which the name is created MUST - result in an entry containing the component name used for the - creation. + Nonetheless, when such a server uses a broader notion of string + equivalence than recommended in the preceding paragraph the following + considerations apply: - o A subsequent lookup using any other string as the component name - SHOULD NOT find the originally created object. + o Outside of 7-bit ASCII, string processing that changes string + contents is usually specific to a character set and hence is + generally unsafe when the character set is unknown. This + processing could change the filename in an unexpected fashion, + rendering the file inaccessible to the application or client that + created or renamed the file and to others expecting the original + filename. - o A subsequent lookup using any valid UTF-8 string MUST NOT find the - originally created object. + o Unicode normalization is particularly dangerous, as such + processing assumes that the string is UTF-8. When that assumption + is false because a different character set was used to create the + filename, normalization may corrupt the filename with respect to + that character set, rendering the file inaccessible to the + application that created it and others expecting the original + filename. - When a lookup of a component name which is not valid UTF-8 occurs, - and is allowed by the server: + When non-UTF-8 component names are accepted in an environment in + which string processing occurs (e.g., to support a broader notion of + string equivalence than binary equality), the following + considerations apply: - o The result of the lookup MUST NOT be any directory entry created - with a valid UTF-8 component name. + o Portions of a string that are not valid UTF-8 cannot be Unicode + normalized because they do not represent Unicode characters. - o The result of the lookup MUST be a directory entry created with - the identical invalid UTF-8 string, if one exists in the - directory. + o Nonetheless, it is possible to perform Unicode normalization on + valid UTF-8 substrings in a string that is not valid UTF-8 by + selectively ignoring substrings that are not valid UTF-8. This + MUST NOT be done since doing so would result in incorrect string + modification or aliasing. 13. Error Values NFS error numbers are assigned to failed operations within a Compound (COMPOUND or CB_COMPOUND) request. A Compound request contains a number of NFS operations that have their results encoded in sequence in a Compound reply. The results of successful operations will consist of an NFS4_OK status followed by the encoded results of the operation. If an NFS operation fails, an error status will be entered in the reply and the Compound request will be terminated. @@ -8549,21 +8615,21 @@ Names in NFSv4 are UTF-8 strings. When the strings are not of length zero, the error NFS4ERR_INVAL results. When they are not valid UTF-8 the error NFS4ERR_INVAL also results, but servers may accommodate file systems with different character formats and not return this error. Besides this, there are a number of other errors to indicate specific problems with names. 13.1.7.1. NFS4ERR_BADCHAR (Error Code 10040) A UTF-8 string contains a character which is not supported by the - server in the context in which it being used. + server in the context in which it is being used. 13.1.7.2. NFS4ERR_BADNAME (Error Code 10041) A name string in a request consisted of valid UTF-8 characters supported by the server but the name is not supported by the server as a valid name for current operation. An example might be creating a file or directory named ".." on a server whose file system uses that name for links to parent directories. This error should not be returned due a normalization issue in a @@ -9915,24 +9981,21 @@ server will return the error NFS4ERR_EXIST. For the directory where the new file object was created, the server returns change_info4 information in cinfo. With the atomic field of the change_info4 struct, the server will indicate if the before and after change attributes were obtained atomically with respect to the file object creation. If the objname is of zero length, NFS4ERR_INVAL will be returned. The objname is also subject to the normal UTF-8, character support, - and name checks. See Section 12.6 for further discussion. - - If the objname has a length of 0 (zero), or if objname does not obey - the UTF-8 definition, the error NFS4ERR_INVAL will be returned. + and name checks. See Section 12.7 for further discussion. The current filehandle is replaced by that of the new object. The createattrs specifies the initial set of attributes for the object. The set of attributes may include any writable attribute valid for the object type. When the operation is successful, the server will return to the client an attribute mask signifying which attributes were successfully set for the object. If createattrs includes neither the owner attribute nor an ACL with @@ -9985,21 +10048,21 @@ nfsstat4 status; }; 15.7.4. DESCRIPTION Purges all of the delegations awaiting recovery for a given client. This is useful for clients which do not commit delegation information to stable storage to indicate that conflicting requests need not be delayed by the server awaiting recovery of delegation information. - This operation in provided to support clients that record delegation + This operation is provided to support clients that record delegation information on stable storage on the client. In this case, DELEGPURGE should be issued immediately after doing delegation recovery (using CLAIM_DELEGATE_PREV) on all delegations known to the client. Doing so will notify the server that no additional delegations for the client will be recovered allowing it to free resources, and avoid delaying other clients who make requests that conflict with the unrecovered delegations. All client SHOULD use DELEGPURGE as part of recovery once it is known that no further CLAIM_DELEGATE_PREV recovery will be done. This includes clients that do not record delegation information on stable storage, who @@ -10588,21 +10651,21 @@ component and if the object exists the current filehandle is replaced with the component's filehandle. If the component cannot be evaluated either because it does not exist or because the client does not have permission to evaluate the component, then an error will be returned and the current filehandle will be unchanged. If the component is of zero length, NFS4ERR_INVAL will be returned. The component is also subject to the normal UTF-8, character support, - and name checks. See Section 12.6 for further discussion. + and name checks. See Section 12.7 for further discussion. 15.15.5. IMPLEMENTATION If the client wants to achieve the effect of a multi-component lookup, it may construct a COMPOUND request such as (and obtain each filehandle): PUTFH (directory filehandle) LOOKUP "pub" GETFH @@ -11061,21 +11124,21 @@ OPEN4_RESULT_CONFIRM indicates that the client MUST execute an OPEN_CONFIRM operation before using the open file. OPEN4_RESULT_LOCKTYPE_POSIX indicates the server's file locking behavior supports the complete set of Posix locking techniques [fcntl]. From this the client can choose to manage file locking state in a way to handle a mis-match of file locking management. If the component is of zero length, NFS4ERR_INVAL will be returned. The component is also subject to the normal UTF-8, character support, - and name checks. See Section 12.6 for further discussion. + and name checks. See Section 12.7 for further discussion. When an OPEN is done and the specified open-owner already has the resulting filehandle open, the result is to "OR" together the new share and deny status together with the existing status. In this case, only a single CLOSE need be done, even though multiple OPENs were completed. When such an OPEN is done, checking of share reservations for the new OPEN proceeds normally, with no exception for the existing OPEN held by the same owner. In this case, the stateid returned as an "other" field that matches that of the previous open while the "seqid" field is incremented to reflect the @@ -11874,34 +11937,34 @@ union REMOVE4res switch (nfsstat4 status) { case NFS4_OK: REMOVE4resok resok4; default: void; }; 15.28.4. DESCRIPTION - The REMOVE operation removes (deletes) a directory entry M named by + The REMOVE operation removes (deletes) a directory entry named by filename from the directory corresponding to the current filehandle. If the entry in the directory was the last reference to the corresponding file system object, the object may be destroyed. For the directory where the filename was removed, the server returns change_info4 information in cinfo. With the atomic field of the change_info4 struct, the server will indicate if the before and after change attributes were obtained atomically with respect to the removal. If the target is of zero length, NFS4ERR_INVAL will be returned. The target is also subject to the normal UTF-8, character support, and - name checks. See Section 12.6 for further discussion. + name checks. See Section 12.7 for further discussion. On success, the current filehandle retains its value. 15.28.5. IMPLEMENTATION NFSv3 required a different operator RMDIR for directory removal and REMOVE for non-directory removal. This allowed clients to skip checking the file type when being passed a non-directory delete system call (e.g., unlink() [unlink] in POSIX) to remove a directory, as well as the converse (e.g., a rmdir() on a non-directory) because @@ -11995,21 +12058,21 @@ struct, the server will indicate if the before and after change attributes were obtained atomically with respect to the rename. If the oldname refers to a named attribute and the saved and current filehandles refer to different file system objects, the server will return NFS4ERR_XDEV just as if the saved and current filehandles represented directories on different file systems. If the oldname or newname is of zero length, NFS4ERR_INVAL will be returned. The oldname and newname are also subject to the normal - UTF-8, character support, and name checks. See Section 12.6 for + UTF-8, character support, and name checks. See Section 12.7 for further discussion. 15.29.5. IMPLEMENTATION The RENAME operation must be atomic to the client. The statement "source and target directories must reside on the same file system on the server" means that the fsid fields in the attributes for the directories are the same. If they reside on different file systems, the error, NFS4ERR_XDEV, is returned.