| draft-ietf-nfsv4-rfc3530bis-02.txt | | draft-ietf-nfsv4-rfc3530bis-03.txt | |
| | | | |
| NFSv4 T. Haynes | | NFSv4 T. Haynes | |
| Internet-Draft Editor | | Internet-Draft Editor | |
| Intended status: Standards Track March 05, 2010 | | Intended status: Standards Track March 05, 2010 | |
| Expires: September 6, 2010 | | Expires: September 6, 2010 | |
| | | | |
| NFS Version 4 Protocol | | NFS Version 4 Protocol | |
|
| draft-ietf-nfsv4-rfc3530bis-02.txt | | draft-ietf-nfsv4-rfc3530bis-03.txt | |
| | | | |
| Abstract | | Abstract | |
| | | | |
| The Network File System (NFS) version 4 is a distributed filesystem | | The Network File System (NFS) version 4 is a distributed filesystem | |
| protocol which owes heritage to NFS protocol version 2, RFC 1094, and | | protocol which owes heritage to NFS protocol version 2, RFC 1094, and | |
| version 3, RFC 1813. Unlike earlier versions, the NFS version 4 | | version 3, RFC 1813. Unlike earlier versions, the NFS version 4 | |
| protocol supports traditional file access while integrating support | | protocol supports traditional file access while integrating support | |
| for file locking and the mount protocol. In addition, support for | | for file locking and the mount protocol. In addition, support for | |
| strong security (and its negotiation), compound operations, client | | strong security (and its negotiation), compound operations, client | |
| caching, and internationalization have been added. Of course, | | caching, and internationalization have been added. Of course, | |
| | | | |
| skipping to change at page 3, line 7 | | skipping to change at page 3, line 7 | |
| modifications of such material outside the IETF Standards Process. | | modifications of such material outside the IETF Standards Process. | |
| Without obtaining an adequate license from the person(s) controlling | | Without obtaining an adequate license from the person(s) controlling | |
| the copyright in such materials, this document may not be modified | | the copyright in such materials, this document may not be modified | |
| outside the IETF Standards Process, and derivative works of it may | | outside the IETF Standards Process, and derivative works of it may | |
| not be created outside the IETF Standards Process, except to format | | not be created outside the IETF Standards Process, except to format | |
| it for publication as an RFC or to translate it into languages other | | it for publication as an RFC or to translate it into languages other | |
| than English. | | than English. | |
| | | | |
| Table of Contents | | Table of Contents | |
| | | | |
|
| 1. XDR Description of NFSv4.1 . . . . . . . . . . . . . . . . . . 3 | | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 | |
| 2. Security Considerations . . . . . . . . . . . . . . . . . . . 36 | | 1.1. Changes since RFC 3530 . . . . . . . . . . . . . . . . . 7 | |
| 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 | | 1.2. Changes since RFC 3010 . . . . . . . . . . . . . . . . . 7 | |
| 4. Normative References . . . . . . . . . . . . . . . . . . . . . 36 | | 1.3. NFS Version 4 Goals . . . . . . . . . . . . . . . . . . 8 | |
| Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 36 | | 1.4. Inconsistencies of this Document with Section 18 . . . . 9 | |
| | | 1.5. Overview of NFS version 4 Features . . . . . . . . . . . 9 | |
| | | 1.5.1. RPC and Security . . . . . . . . . . . . . . . . . . 9 | |
| | | 1.5.2. Procedure and Operation Structure . . . . . . . . . . 10 | |
| | | 1.5.3. Filesystem Model . . . . . . . . . . . . . . . . . . 10 | |
| | | 1.5.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 12 | |
| | | 1.5.5. File locking . . . . . . . . . . . . . . . . . . . . 12 | |
| | | 1.5.6. Client Caching and Delegation . . . . . . . . . . . . 13 | |
| | | 1.6. General Definitions . . . . . . . . . . . . . . . . . . 13 | |
| | | 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . . . 15 | |
| | | 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 15 | |
| | | 2.2. Structured Data Types . . . . . . . . . . . . . . . . . 17 | |
| | | 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . . . 22 | |
| | | 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 22 | |
| | | 3.1.1. Client Retransmission Behavior . . . . . . . . . . . 23 | |
| | | 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 23 | |
| | | 3.2.1. Security mechanisms for NFS version 4 . . . . . . . . 24 | |
| | | 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 26 | |
| | | 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . . 26 | |
| | | 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 27 | |
| | | 3.3.3. Callback RPC Authentication . . . . . . . . . . . . . 27 | |
| | | 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 29 | |
| | | 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 29 | |
| | | 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . . 29 | |
| | | 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . . 30 | |
| | | 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 30 | |
| | | 4.2.1. General Properties of a Filehandle . . . . . . . . . 30 | |
| | | 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . . 31 | |
| | | 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 31 | |
| | | 4.2.4. One Method of Constructing a Volatile Filehandle . . 33 | |
| | | 4.3. Client Recovery from Filehandle Expiration . . . . . . . 33 | |
| | | 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 34 | |
| | | 5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 35 | |
| | | 5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 35 | |
| | | 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 36 | |
| | | 5.4. Classification of Attributes . . . . . . . . . . . . . . 36 | |
| | | 5.5. Mandatory Attributes - Definitions . . . . . . . . . . . 37 | |
| | | 5.6. Recommended Attributes - Definitions . . . . . . . . . . 39 | |
| | | 5.7. Time Access . . . . . . . . . . . . . . . . . . . . . . 45 | |
| | | 5.8. Interpreting owner and owner_group . . . . . . . . . . . 46 | |
| | | 5.9. Character Case Attributes . . . . . . . . . . . . . . . 48 | |
| | | 5.10. Quota Attributes . . . . . . . . . . . . . . . . . . . . 48 | |
| | | 5.11. Access Control Lists . . . . . . . . . . . . . . . . . . 49 | |
| | | 5.11.1. ACE type . . . . . . . . . . . . . . . . . . . . . . 50 | |
| | | 5.11.2. ACE Access Mask . . . . . . . . . . . . . . . . . . . 51 | |
| | | 5.11.3. ACE flag . . . . . . . . . . . . . . . . . . . . . . 53 | |
| | | 5.11.4. ACE who . . . . . . . . . . . . . . . . . . . . . . . 55 | |
| | | 5.11.5. Mode Attribute . . . . . . . . . . . . . . . . . . . 56 | |
| | | 5.11.6. Mode and ACL Attribute . . . . . . . . . . . . . . . 57 | |
| | | 5.11.7. mounted_on_fileid . . . . . . . . . . . . . . . . . . 57 | |
| | | 6. Filesystem Migration and Replication . . . . . . . . . . . . 58 | |
| | | 6.1. Replication . . . . . . . . . . . . . . . . . . . . . . 59 | |
| | | 6.2. Migration . . . . . . . . . . . . . . . . . . . . . . . 59 | |
| | | 6.3. Interpretation of the fs_locations Attribute . . . . . . 60 | |
| | | 6.4. Filehandle Recovery for Migration or Replication . . . . 61 | |
| | | 7. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 61 | |
| | | 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 61 | |
| | | 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 62 | |
| | | 7.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 62 | |
| | | 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 63 | |
| | | 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 63 | |
| | | 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 63 | |
| | | 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 63 | |
| | | 7.8. Security Policy and Name Space Presentation . . . . . . 64 | |
| | | 8. File Locking and Share Reservations . . . . . . . . . . . . . 65 | |
| | | 8.1. Locking . . . . . . . . . . . . . . . . . . . . . . . . 65 | |
| | | 8.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 66 | |
| | | 8.1.2. Server Release of Clientid . . . . . . . . . . . . . 69 | |
| | | 8.1.3. lock_owner and stateid Definition . . . . . . . . . . 69 | |
| | | 8.1.4. Use of the stateid and Locking . . . . . . . . . . . 71 | |
| | | 8.1.5. Sequencing of Lock Requests . . . . . . . . . . . . . 73 | |
| | | 8.1.6. Recovery from Replayed Requests . . . . . . . . . . . 74 | |
| | | 8.1.7. Releasing lock_owner State . . . . . . . . . . . . . 74 | |
| | | 8.1.8. Use of Open Confirmation . . . . . . . . . . . . . . 75 | |
| | | 8.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 76 | |
| | | 8.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 76 | |
| | | 8.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 77 | |
| | | 8.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 77 | |
| | | 8.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 78 | |
| | | 8.6.1. Client Failure and Recovery . . . . . . . . . . . . . 78 | |
| | | 8.6.2. Server Failure and Recovery . . . . . . . . . . . . . 79 | |
| | | 8.6.3. Network Partitions and Recovery . . . . . . . . . . . 81 | |
| | | 8.7. Recovery from a Lock Request Timeout or Abort . . . . . 84 | |
| | | 8.8. Server Revocation of Locks . . . . . . . . . . . . . . . 85 | |
| | | 8.9. Share Reservations . . . . . . . . . . . . . . . . . . . 86 | |
| | | 8.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 87 | |
| | | 8.10.1. Close and Retention of State Information . . . . . . 87 | |
| | | 8.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 88 | |
| | | 8.12. Short and Long Leases . . . . . . . . . . . . . . . . . 89 | |
| | | 8.13. Clocks, Propagation Delay, and Calculating Lease | |
| | | Expiration . . . . . . . . . . . . . . . . . . . . . . . 89 | |
| | | 8.14. Migration, Replication and State . . . . . . . . . . . . 90 | |
| | | 8.14.1. Migration and State . . . . . . . . . . . . . . . . . 90 | |
| | | 8.14.2. Replication and State . . . . . . . . . . . . . . . . 91 | |
| | | 8.14.3. Notification of Migrated Lease . . . . . . . . . . . 91 | |
| | | 8.14.4. Migration and the Lease_time Attribute . . . . . . . 92 | |
| | | 9. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 93 | |
| | | 9.1. Performance Challenges for Client-Side Caching . . . . . 93 | |
| | | 9.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 94 | |
| | | 9.2.1. Delegation Recovery . . . . . . . . . . . . . . . . . 95 | |
| | | 9.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 97 | |
| | | 9.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 98 | |
| | | 9.3.2. Data Caching and File Locking . . . . . . . . . . . . 99 | |
| | | 9.3.3. Data Caching and Mandatory File Locking . . . . . . . 100 | |
| | | 9.3.4. Data Caching and File Identity . . . . . . . . . . . 101 | |
| | | 9.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 102 | |
| | | 9.4.1. Open Delegation and Data Caching . . . . . . . . . . 104 | |
| | | 9.4.2. Open Delegation and File Locks . . . . . . . . . . . 105 | |
| | | 9.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 106 | |
| | | 9.4.4. Recall of Open Delegation . . . . . . . . . . . . . . 109 | |
| | | 9.4.5. Clients that Fail to Honor Delegation Recalls . . . . 111 | |
| | | 9.4.6. Delegation Revocation . . . . . . . . . . . . . . . . 111 | |
| | | 9.5. Data Caching and Revocation . . . . . . . . . . . . . . 112 | |
| | | 9.5.1. Revocation Recovery for Write Open Delegation . . . . 112 | |
| | | 9.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 113 | |
| | | 9.7. Data and Metadata Caching and Memory Mapped Files . . . 115 | |
| | | 9.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 117 | |
| | | 9.9. Directory Caching . . . . . . . . . . . . . . . . . . . 118 | |
| | | 10. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 119 | |
| | | 11. Internationalization . . . . . . . . . . . . . . . . . . . . 122 | |
| | | 11.1. Stringprep profile for the utf8str_cs type . . . . . . . 123 | |
| | | 11.1.1. Intended applicability of the nfs4_cs_prep profile . 123 | |
| | | 11.1.2. Character repertoire of nfs4_cs_prep . . . . . . . . 123 | |
| | | 11.1.3. Mapping used by nfs4_cs_prep . . . . . . . . . . . . 123 | |
| | | 11.1.4. Normalization used by nfs4_cs_prep . . . . . . . . . 124 | |
| | | 11.1.5. Prohibited output for nfs4_cs_prep . . . . . . . . . 124 | |
| | | 11.1.6. Bidirectional output for nfs4_cs_prep . . . . . . . . 124 | |
| | | 11.2. Stringprep profile for the utf8str_cis type . . . . . . 124 | |
| | | 11.2.1. Intended applicability of the nfs4_cis_prep profile . 125 | |
| | | 11.2.2. Character repertoire of nfs4_cis_prep . . . . . . . . 125 | |
| | | 11.2.3. Mapping used by nfs4_cis_prep . . . . . . . . . . . . 125 | |
| | | 11.2.4. Normalization used by nfs4_cis_prep . . . . . . . . . 125 | |
| | | 11.2.5. Prohibited output for nfs4_cis_prep . . . . . . . . . 125 | |
| | | 11.2.6. Bidirectional output for nfs4_cis_prep . . . . . . . 126 | |
| | | 11.3. Stringprep profile for the utf8str_mixed type . . . . . 126 | |
| | | 11.3.1. Intended applicability of the nfs4_mixed_prep | |
| | | profile . . . . . . . . . . . . . . . . . . . . . . . 126 | |
| | | 11.3.2. Character repertoire of nfs4_mixed_prep . . . . . . . 126 | |
| | | 11.3.3. Mapping used by nfs4_cis_prep . . . . . . . . . . . . 126 | |
| | | 11.3.4. Normalization used by nfs4_mixed_prep . . . . . . . . 126 | |
| | | 11.3.5. Prohibited output for nfs4_mixed_prep . . . . . . . . 126 | |
| | | 11.3.6. Bidirectional output for nfs4_mixed_prep . . . . . . 127 | |
| | | 11.4. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 127 | |
| | | 12. Error Definitions . . . . . . . . . . . . . . . . . . . . . . 128 | |
| | | 13. NFS version 4 Requests . . . . . . . . . . . . . . . . . . . 133 | |
| | | 13.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 133 | |
| | | 13.2. Evaluation of a Compound Request . . . . . . . . . . . . 134 | |
| | | 13.3. Synchronous Modifying Operations . . . . . . . . . . . . 135 | |
| | | 13.4. Operation Values . . . . . . . . . . . . . . . . . . . . 135 | |
| | | 14. NFS version 4 Procedures . . . . . . . . . . . . . . . . . . 135 | |
| | | 14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 135 | |
| | | 14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 136 | |
| | | 14.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 139 | |
| | | 14.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 142 | |
| | | 14.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 143 | |
| | | 14.6. Operation 6: CREATE - Create a Non-Regular File Object . 146 | |
| | | 14.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting | |
| | | Recovery . . . . . . . . . . . . . . . . . . . . . . . . 149 | |
| | | 14.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 150 | |
| | | 14.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 151 | |
| | | 14.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 153 | |
| | | 14.11. Operation 11: LINK - Create Link to a File . . . . . . . 154 | |
| | | 14.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 156 | |
| | | 14.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 160 | |
| | | 14.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 162 | |
| | | 14.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 164 | |
| | | 14.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 166 | |
| | | 14.17. Operation 17: NVERIFY - Verify Difference in | |
| | | Attributes . . . . . . . . . . . . . . . . . . . . . . . 167 | |
| | | 14.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 169 | |
| | | 14.19. Operation 19: OPENATTR - Open Named Attribute | |
| | | Directory . . . . . . . . . . . . . . . . . . . . . . . 179 | |
| | | 14.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 181 | |
| | | 14.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 184 | |
| | | 14.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 185 | |
| | | 14.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 186 | |
| | | 14.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 188 | |
| | | 14.25. Operation 25: READ - Read from File . . . . . . . . . . 188 | |
| | | 14.26. Operation 26: READDIR - Read Directory . . . . . . . . . 191 | |
| | | 14.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 195 | |
| | | 14.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 196 | |
| | | 14.29. Operation 29: RENAME - Rename Directory Entry . . . . . 199 | |
| | | 14.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 202 | |
| | | 14.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 204 | |
| | | 14.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 205 | |
| | | 14.33. Operation 33: SECINFO - Obtain Available Security . . . 206 | |
| | | 14.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 210 | |
| | | 14.35. Operation 35: SETCLIENTID - Negotiate Clientid . . . . . 213 | |
| | | 14.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid . . 216 | |
| | | 14.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 220 | |
| | | 14.38. Operation 38: WRITE - Write to File . . . . . . . . . . 222 | |
| | | 14.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner | |
| | | State . . . . . . . . . . . . . . . . . . . . . . . . . 226 | |
| | | 14.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 228 | |
| | | 15. NFS version 4 Callback Procedures . . . . . . . . . . . . . . 228 | |
| | | 15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 229 | |
| | | 15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 229 | |
| | | 15.2.7. Operation 3: CB_GETATTR - Get Attributes . . . . . . 231 | |
| | | 15.2.8. Operation 4: CB_RECALL - Recall an Open Delegation . 232 | |
| | | 15.2.9. Operation 10044: CB_ILLEGAL - Illegal Callback | |
| | | Operation . . . . . . . . . . . . . . . . . . . . . . 234 | |
| | | 16. Security Considerations . . . . . . . . . . . . . . . . . . . 234 | |
| | | 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 236 | |
| | | 17.1. Named Attribute Definition . . . . . . . . . . . . . . . 236 | |
| | | 17.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 236 | |
| | | 18. References . . . . . . . . . . . . . . . . . . . . . . . . . 238 | |
| | | 18.1. Normative References . . . . . . . . . . . . . . . . . . 238 | |
| | | 18.2. Informative References . . . . . . . . . . . . . . . . . 238 | |
| | | Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 240 | |
| | | Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 240 | |
| | | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 240 | |
| | | | |
|
| 1. XDR Description of NFSv4.1 | | 1. Introduction | |
| | | | |
|
| This document contains the XDR ([2]) description of NFSv4.0 protocol | | 1.1. Changes since RFC 3530 | |
| ([3]). | | | |
| | | | |
|
| The XDR description is provided in this document in a way that makes | | This document obsoletes RFC 3530 [10] as the authoritative document | |
| it simple for the reader to extract into ready to compile form. The | | describing NFSv4, without introducing any over-the-wire protocol | |
| reader can feed this document in the following shell script to | | changes. The main changes from RFC 3530 are: | |
| produce the machine readable XDR description of NFSv4.0: | | | |
| | | | |
|
| #!/bin/sh | | o The RPC definition has been moved to a companion document [2] | |
| grep "^ *///" | sed 's?^ */// ??' | sed 's?^ *///$??' | | | |
| | | | |
|
| I.e. if the above script is stored in a file called "extract.sh", and | | o Updates for the latest IETF intellectual property statements | |
| this document is in a file called "spec.txt", then the reader can do: | | | |
| | | | |
|
| sh extract.sh < spec.txt > nfs4_prot.x | | o LIPKEY SPKM/3 has been moved from being mandatory to optional | |
| | | | |
|
| The effect of the script is to remove leading white space from each | | o Some clarification on a client re-establishing callback | |
| line, plus a sentinel sequence of "///". | | information to the new server if state has been migrated | |
| | | | |
|
| The XDR description, with the sentinel sequence follows: | | 1.2. Changes since RFC 3010 | |
| | | | |
|
| /// /* | | This definition of the NFS version 4 protocol replaces or obsoletes | |
| /// * This file was machine generated for | | the definition present in [11]. While portions of the two documents | |
| /// * draft-ietf-nfsv4-rfc3530bis-01 | | have remained the same, there have been substantive changes in | |
| /// * Last updated Friday, March 5, 2010 03:42:34 PM CST | | others. The changes made between [11] and this document represent | |
| /// */ | | implementation experience and further review of the protocol. While | |
| /// /* | | some modifications were made for ease of implementation or | |
| /// * Copyright (C) The IETF Trust (2007-2008) | | clarification, most updates represent errors or situations where the | |
| /// * All Rights Reserved. | | [11] definition were untenable. | |
| /// * | | | |
| /// * Copyright (C) The Internet Society (1998-2006). | | | |
| /// * All Rights Reserved. | | | |
| /// */ | | | |
| /// | | | |
| /// /* | | | |
| /// * nfs4_prot.x | | | |
| /// * | | | |
| /// */ | | | |
| /// | | | |
| /// /* | | | |
| /// * Basic typedefs for RFC 1832 data type definitions | | | |
| /// */ | | | |
| /// /* | | | |
| /// * typedef int int32_t; | | | |
| /// * typedef unsigned int uint32_t; | | | |
| /// * typedef hyper int64_t; | | | |
| /// * typedef unsigned hyper uint64_t; | | | |
| /// */ | | | |
| /// | | | |
| /// /* | | | |
| /// * Sizes | | | |
| /// */ | | | |
| /// const NFS4_FHSIZE = 128; | | | |
| /// const NFS4_VERIFIER_SIZE = 8; | | | |
| /// const NFS4_OPAQUE_LIMIT = 1024; | | | |
| /// | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * File types | | | |
| /// */ | | | |
| /// enum nfs_ftype4 { | | | |
| /// NF4REG = 1, /* Regular File */ | | | |
| /// NF4DIR = 2, /* Directory */ | | | |
| /// NF4BLK = 3, /* Special File - block device */ | | | |
| /// NF4CHR = 4, /* Special File - character device */ | | | |
| /// NF4LNK = 5, /* Symbolic Link */ | | | |
| /// NF4SOCK = 6, /* Special File - socket */ | | | |
| /// NF4FIFO = 7, /* Special File - fifo */ | | | |
| /// NF4ATTRDIR | | | |
| /// = 8, /* Attribute Directory */ | | | |
| /// NF4NAMEDATTR | | | |
| /// = 9 /* Named Attribute */ | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * Error status | | | |
| /// */ | | | |
| /// enum nfsstat4 { | | | |
| /// NFS4_OK = 0, /* everything is okay */ | | | |
| /// NFS4ERR_PERM = 1, /* caller not privileged */ | | | |
| /// NFS4ERR_NOENT = 2, /* no such file/directory */ | | | |
| /// NFS4ERR_IO = 5, /* hard I/O error */ | | | |
| /// NFS4ERR_NXIO = 6, /* no such device */ | | | |
| /// NFS4ERR_ACCESS = 13, /* access denied */ | | | |
| /// NFS4ERR_EXIST = 17, /* file already exists */ | | | |
| /// NFS4ERR_XDEV = 18, /* different filesystems */ | | | |
| /// /* Unused/reserved 19 */ | | | |
| /// NFS4ERR_NOTDIR = 20, /* should be a directory */ | | | |
| /// NFS4ERR_ISDIR = 21, /* should not be directory */ | | | |
| /// NFS4ERR_INVAL = 22, /* invalid argument */ | | | |
| /// NFS4ERR_FBIG = 27, /* file exceeds server max */ | | | |
| /// NFS4ERR_NOSPC = 28, /* no space on filesystem */ | | | |
| /// NFS4ERR_ROFS = 30, /* read-only filesystem */ | | | |
| /// NFS4ERR_MLINK = 31, /* too many hard links */ | | | |
| /// NFS4ERR_NAMETOOLONG = 63, /* name exceeds server max */ | | | |
| /// NFS4ERR_NOTEMPTY = 66, /* directory not empty */ | | | |
| /// NFS4ERR_DQUOT = 69, /* hard quota limit reached*/ | | | |
| /// NFS4ERR_STALE = 70, /* file no longer exists */ | | | |
| /// NFS4ERR_BADHANDLE = 10001,/* Illegal filehandle */ | | | |
| /// NFS4ERR_BAD_COOKIE = 10003,/* READDIR cookie is stale */ | | | |
| /// NFS4ERR_NOTSUPP = 10004,/* operation not supported */ | | | |
| /// NFS4ERR_TOOSMALL = 10005,/* response limit exceeded */ | | | |
| /// NFS4ERR_SERVERFAULT = 10006,/* undefined server error */ | | | |
| /// NFS4ERR_BADTYPE = 10007,/* type invalid for CREATE */ | | | |
| /// NFS4ERR_DELAY = 10008,/* file "busy" - retry */ | | | |
| /// NFS4ERR_SAME = 10009,/* nverify says attrs same */ | | | |
| /// NFS4ERR_DENIED = 10010,/* lock unavailable */ | | | |
| /// NFS4ERR_EXPIRED = 10011,/* lock lease expired */ | | | |
| /// NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */ | | | |
| /// NFS4ERR_GRACE = 10013,/* in grace period */ | | | |
| /// NFS4ERR_FHEXPIRED = 10014,/* filehandle expired */ | | | |
| /// NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */ | | | |
| /// NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */ | | | |
| /// NFS4ERR_CLID_INUSE = 10017,/* clientid in use */ | | | |
| /// NFS4ERR_RESOURCE = 10018,/* resource exhaustion */ | | | |
| /// NFS4ERR_MOVED = 10019,/* filesystem relocated */ | | | |
| /// NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */ | | | |
| /// NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */ | | | |
| /// NFS4ERR_STALE_CLIENTID = 10022,/* server has rebooted */ | | | |
| /// NFS4ERR_STALE_STATEID = 10023,/* server has rebooted */ | | | |
| /// NFS4ERR_OLD_STATEID = 10024,/* state is out of sync */ | | | |
| /// NFS4ERR_BAD_STATEID = 10025,/* incorrect stateid */ | | | |
| /// NFS4ERR_BAD_SEQID = 10026,/* request is out of seq. */ | | | |
| /// NFS4ERR_NOT_SAME = 10027,/* verify - attrs not same */ | | | |
| /// NFS4ERR_LOCK_RANGE = 10028,/* lock range not supported*/ | | | |
| /// NFS4ERR_SYMLINK = 10029,/* should be file/directory*/ | | | |
| /// NFS4ERR_RESTOREFH = 10030,/* no saved filehandle */ | | | |
| /// NFS4ERR_LEASE_MOVED = 10031,/* some filesystem moved */ | | | |
| /// NFS4ERR_ATTRNOTSUPP = 10032,/* recommended attr not sup*/ | | | |
| /// NFS4ERR_NO_GRACE = 10033,/* reclaim outside of grace*/ | | | |
| /// NFS4ERR_RECLAIM_BAD = 10034,/* reclaim error at server */ | | | |
| /// NFS4ERR_RECLAIM_CONFLICT = 10035,/* conflict on reclaim */ | | | |
| /// NFS4ERR_BADXDR = 10036,/* XDR decode failed */ | | | |
| /// NFS4ERR_LOCKS_HELD = 10037,/* file locks held at CLOSE*/ | | | |
| /// NFS4ERR_OPENMODE = 10038,/* conflict in OPEN and I/O*/ | | | |
| /// NFS4ERR_BADOWNER = 10039,/* owner translation bad */ | | | |
| /// NFS4ERR_BADCHAR = 10040,/* utf-8 char not supported*/ | | | |
| /// NFS4ERR_BADNAME = 10041,/* name not supported */ | | | |
| /// NFS4ERR_BAD_RANGE = 10042,/* lock range not supported*/ | | | |
| /// NFS4ERR_LOCK_NOTSUPP = 10043,/* no atomic up/downgrade */ | | | |
| /// NFS4ERR_OP_ILLEGAL = 10044,/* undefined operation */ | | | |
| /// NFS4ERR_DEADLOCK = 10045,/* file locking deadlock */ | | | |
| /// NFS4ERR_FILE_OPEN = 10046,/* open file blocks op. */ | | | |
| /// NFS4ERR_ADMIN_REVOKED = 10047,/* lockowner state revoked */ | | | |
| /// NFS4ERR_CB_PATH_DOWN = 10048 /* callback path down */ | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * Basic data types | | | |
| /// */ | | | |
| /// typedef opaque attrlist4<>; | | | |
| /// typedef uint32_t bitmap4<>; | | | |
| /// typedef uint64_t changeid4; | | | |
| /// typedef uint64_t clientid4; | | | |
| /// typedef uint32_t count4; | | | |
| /// typedef uint64_t length4; | | | |
| /// typedef uint32_t mode4; | | | |
| /// typedef uint64_t nfs_cookie4; | | | |
| /// typedef opaque nfs_fh4<NFS4_FHSIZE>; | | | |
| /// typedef uint64_t offset4; | | | |
| /// typedef uint32_t qop4; | | | |
| /// typedef opaque sec_oid4<>; | | | |
| /// typedef uint32_t seqid4; | | | |
| /// typedef opaque utf8string<>; | | | |
| /// typedef utf8string utf8str_cis; | | | |
| /// typedef utf8string utf8str_cs; | | | |
| /// typedef utf8string utf8str_mixed; | | | |
| /// typedef utf8str_cs component4; | | | |
| /// typedef utf8str_cs linktext4; | | | |
| /// typedef component4 pathname4<>; | | | |
| /// typedef uint64_t nfs_lockid4; | | | |
| /// typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Timeval | | | |
| /// */ | | | |
| /// struct nfstime4 { | | | |
| /// int64_t seconds; | | | |
| /// uint32_t nseconds; | | | |
| /// }; | | | |
| /// | | | |
| /// enum time_how4 { | | | |
| /// SET_TO_SERVER_TIME4 = 0, | | | |
| /// SET_TO_CLIENT_TIME4 = 1 | | | |
| /// }; | | | |
| /// | | | |
| /// union settime4 switch (time_how4 set_it) { | | | |
| /// case SET_TO_CLIENT_TIME4: | | | |
| /// nfstime4 time; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * File attribute definitions | | | |
| /// */ | | | |
| /// | | | |
| /// /* | | | |
| /// * FSID structure for major/minor | | | |
| /// */ | | | |
| /// struct fsid4 { | | | |
| /// uint64_t major; | | | |
| /// uint64_t minor; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Filesystem locations attribute for relocation/migration | | | |
| /// */ | | | |
| /// struct fs_location4 { | | | |
| /// utf8str_cis server<>; | | | |
| /// pathname4 rootpath; | | | |
| /// }; | | | |
| /// | | | |
| /// struct fs_locations4 { | | | |
| /// pathname4 fs_root; | | | |
| /// fs_location4 locations<>; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Various Access Control Entry definitions | | | |
| /// */ | | | |
| /// | | | |
| /// /* | | | |
| /// * Mask that indicates which Access Control Entries | | | |
| /// * are supported. Values for the fattr4_aclsupport attribute. | | | |
| /// */ | | | |
| /// const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; | | | |
| /// const ACL4_SUPPORT_DENY_ACL = 0x00000002; | | | |
| /// const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; | | | |
| /// const ACL4_SUPPORT_ALARM_ACL = 0x00000008; | | | |
| /// | | | |
| /// | | | |
| /// typedef uint32_t acetype4; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * acetype4 values, others can be added as needed. | | | |
| /// */ | | | |
| /// const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; | | | |
| /// const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; | | | |
| /// const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; | | | |
| /// const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; | | | |
| /// | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * ACE flag | | | |
| /// */ | | | |
| /// typedef uint32_t aceflag4; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * ACE flag values | | | |
| /// */ | | | |
| /// const ACE4_FILE_INHERIT_ACE = 0x00000001; | | | |
| /// const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; | | | |
| /// const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; | | | |
| /// const ACE4_INHERIT_ONLY_ACE = 0x00000008; | | | |
| /// const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; | | | |
| /// const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; | | | |
| /// const ACE4_IDENTIFIER_GROUP = 0x00000040; | | | |
| /// | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * ACE mask | | | |
| /// */ | | | |
| /// typedef uint32_t acemask4; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * ACE mask values | | | |
| /// */ | | | |
| /// const ACE4_READ_DATA = 0x00000001; | | | |
| /// const ACE4_LIST_DIRECTORY = 0x00000001; | | | |
| /// const ACE4_WRITE_DATA = 0x00000002; | | | |
| /// const ACE4_ADD_FILE = 0x00000002; | | | |
| /// const ACE4_APPEND_DATA = 0x00000004; | | | |
| /// const ACE4_ADD_SUBDIRECTORY = 0x00000004; | | | |
| /// const ACE4_READ_NAMED_ATTRS = 0x00000008; | | | |
| /// const ACE4_WRITE_NAMED_ATTRS = 0x00000010; | | | |
| /// const ACE4_EXECUTE = 0x00000020; | | | |
| /// const ACE4_DELETE_CHILD = 0x00000040; | | | |
| /// const ACE4_READ_ATTRIBUTES = 0x00000080; | | | |
| /// const ACE4_WRITE_ATTRIBUTES = 0x00000100; | | | |
| /// | | | |
| /// const ACE4_DELETE = 0x00010000; | | | |
| /// const ACE4_READ_ACL = 0x00020000; | | | |
| /// const ACE4_WRITE_ACL = 0x00040000; | | | |
| /// const ACE4_WRITE_OWNER = 0x00080000; | | | |
| /// const ACE4_SYNCHRONIZE = 0x00100000; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * ACE4_GENERIC_READ -- defined as combination of | | | |
| /// * ACE4_READ_ACL | | | | |
| /// * ACE4_READ_DATA | | | | |
| /// * ACE4_READ_ATTRIBUTES | | | | |
| /// * ACE4_SYNCHRONIZE | | | |
| /// */ | | | |
| /// | | | |
| /// const ACE4_GENERIC_READ = 0x00120081; | | | |
| /// | | | |
| /// /* | | | |
| /// * ACE4_GENERIC_WRITE -- defined as combination of | | | |
| /// * ACE4_READ_ACL | | | | |
| /// * ACE4_WRITE_DATA | | | | |
| /// * ACE4_WRITE_ATTRIBUTES | | | | |
| /// * ACE4_WRITE_ACL | | | | |
| /// * ACE4_APPEND_DATA | | | | |
| /// * ACE4_SYNCHRONIZE | | | |
| /// */ | | | |
| /// const ACE4_GENERIC_WRITE = 0x00160106; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * ACE4_GENERIC_EXECUTE -- defined as combination of | | | |
| /// * ACE4_READ_ACL | | | |
| /// * ACE4_READ_ATTRIBUTES | | | |
| /// * ACE4_EXECUTE | | | |
| /// * ACE4_SYNCHRONIZE | | | |
| /// */ | | | |
| /// const ACE4_GENERIC_EXECUTE = 0x001200A0; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Access Control Entry definition | | | |
| /// */ | | | |
| /// struct nfsace4 { | | | |
| /// acetype4 type; | | | |
| /// aceflag4 flag; | | | |
| /// acemask4 access_mask; | | | |
| /// utf8str_mixed who; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Field definitions for the fattr4_mode attribute | | | |
| /// */ | | | |
| /// const MODE4_SUID = 0x800; /* set user id on execution */ | | | |
| /// const MODE4_SGID = 0x400; /* set group id on execution */ | | | |
| /// const MODE4_SVTX = 0x200; /* save text even after use */ | | | |
| /// const MODE4_RUSR = 0x100; /* read permission: owner */ | | | |
| /// const MODE4_WUSR = 0x080; /* write permission: owner */ | | | |
| /// const MODE4_XUSR = 0x040; /* execute permission: owner */ | | | |
| /// const MODE4_RGRP = 0x020; /* read permission: group */ | | | |
| /// const MODE4_WGRP = 0x010; /* write permission: group */ | | | |
| /// const MODE4_XGRP = 0x008; /* execute permission: group */ | | | |
| /// const MODE4_ROTH = 0x004; /* read permission: other */ | | | |
| /// const MODE4_WOTH = 0x002; /* write permission: other */ | | | |
| /// const MODE4_XOTH = 0x001; /* execute permission: other */ | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Special data/attribute associated with | | | |
| /// * file types NF4BLK and NF4CHR. | | | |
| /// */ | | | |
| /// struct specdata4 { | | | |
| /// uint32_t specdata1; /* major device number */ | | | |
| /// uint32_t specdata2; /* minor device number */ | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Values for fattr4_fh_expire_type | | | |
| /// */ | | | |
| /// const FH4_PERSISTENT = 0x00000000; | | | |
| /// const FH4_NOEXPIRE_WITH_OPEN = 0x00000001; | | | |
| /// const FH4_VOLATILE_ANY = 0x00000002; | | | |
| /// const FH4_VOL_MIGRATION = 0x00000004; | | | |
| /// const FH4_VOL_RENAME = 0x00000008; | | | |
| /// | | | |
| /// | | | |
| /// typedef bitmap4 fattr4_supported_attrs; | | | |
| /// typedef nfs_ftype4 fattr4_type; | | | |
| /// typedef uint32_t fattr4_fh_expire_type; | | | |
| /// typedef changeid4 fattr4_change; | | | |
| /// typedef uint64_t fattr4_size; | | | |
| /// typedef bool fattr4_link_support; | | | |
| /// typedef bool fattr4_symlink_support; | | | |
| /// typedef bool fattr4_named_attr; | | | |
| /// typedef fsid4 fattr4_fsid; | | | |
| /// typedef bool fattr4_unique_handles; | | | |
| /// typedef uint32_t fattr4_lease_time; | | | |
| /// typedef nfsstat4 fattr4_rdattr_error; | | | |
| /// | | | |
| /// typedef nfsace4 fattr4_acl<>; | | | |
| /// typedef uint32_t fattr4_aclsupport; | | | |
| /// typedef bool fattr4_archive; | | | |
| /// typedef bool fattr4_cansettime; | | | |
| /// typedef bool fattr4_case_insensitive; | | | |
| /// typedef bool fattr4_case_preserving; | | | |
| /// typedef bool fattr4_chown_restricted; | | | |
| /// typedef uint64_t fattr4_fileid; | | | |
| /// typedef uint64_t fattr4_files_avail; | | | |
| /// typedef nfs_fh4 fattr4_filehandle; | | | |
| /// typedef uint64_t fattr4_files_free; | | | |
| /// typedef uint64_t fattr4_files_total; | | | |
| /// typedef fs_locations4 fattr4_fs_locations; | | | |
| /// typedef bool fattr4_hidden; | | | |
| /// typedef bool fattr4_homogeneous; | | | |
| /// typedef uint64_t fattr4_maxfilesize; | | | |
| /// typedef uint32_t fattr4_maxlink; | | | |
| /// typedef uint32_t fattr4_maxname; | | | |
| /// typedef uint64_t fattr4_maxread; | | | |
| /// typedef uint64_t fattr4_maxwrite; | | | |
| /// typedef utf8str_cs fattr4_mimetype; | | | |
| /// typedef mode4 fattr4_mode; | | | |
| /// typedef uint64_t fattr4_mounted_on_fileid; | | | |
| /// typedef bool fattr4_no_trunc; | | | |
| /// typedef uint32_t fattr4_numlinks; | | | |
| /// typedef utf8str_mixed fattr4_owner; | | | |
| /// typedef utf8str_mixed fattr4_owner_group; | | | |
| /// typedef uint64_t fattr4_quota_avail_hard; | | | |
| /// typedef uint64_t fattr4_quota_avail_soft; | | | |
| /// typedef uint64_t fattr4_quota_used; | | | |
| /// typedef specdata4 fattr4_rawdev; | | | |
| /// typedef uint64_t fattr4_space_avail; | | | |
| /// typedef uint64_t fattr4_space_free; | | | |
| /// typedef uint64_t fattr4_space_total; | | | |
| /// typedef uint64_t fattr4_space_used; | | | |
| /// typedef bool fattr4_system; | | | |
| /// typedef nfstime4 fattr4_time_access; | | | |
| /// typedef settime4 fattr4_time_access_set; | | | |
| /// typedef nfstime4 fattr4_time_backup; | | | |
| /// typedef nfstime4 fattr4_time_create; | | | |
| /// typedef nfstime4 fattr4_time_delta; | | | |
| /// typedef nfstime4 fattr4_time_metadata; | | | |
| /// typedef nfstime4 fattr4_time_modify; | | | |
| /// typedef settime4 fattr4_time_modify_set; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Mandatory Attributes | | | |
| /// */ | | | |
| /// const FATTR4_SUPPORTED_ATTRS = 0; | | | |
| /// const FATTR4_TYPE = 1; | | | |
| /// const FATTR4_FH_EXPIRE_TYPE = 2; | | | |
| /// const FATTR4_CHANGE = 3; | | | |
| /// const FATTR4_SIZE = 4; | | | |
| /// const FATTR4_LINK_SUPPORT = 5; | | | |
| /// const FATTR4_SYMLINK_SUPPORT = 6; | | | |
| /// const FATTR4_NAMED_ATTR = 7; | | | |
| /// const FATTR4_FSID = 8; | | | |
| /// const FATTR4_UNIQUE_HANDLES = 9; | | | |
| /// const FATTR4_LEASE_TIME = 10; | | | |
| /// const FATTR4_RDATTR_ERROR = 11; | | | |
| /// const FATTR4_FILEHANDLE = 19; | | | |
| /// | | | |
| /// /* | | | |
| /// * Recommended Attributes | | | |
| /// */ | | | |
| /// const FATTR4_ACL = 12; | | | |
| /// const FATTR4_ACLSUPPORT = 13; | | | |
| /// const FATTR4_ARCHIVE = 14; | | | |
| /// const FATTR4_CANSETTIME = 15; | | | |
| /// const FATTR4_CASE_INSENSITIVE = 16; | | | |
| /// const FATTR4_CASE_PRESERVING = 17; | | | |
| /// const FATTR4_CHOWN_RESTRICTED = 18; | | | |
| /// const FATTR4_FILEID = 20; | | | |
| /// const FATTR4_FILES_AVAIL = 21; | | | |
| /// const FATTR4_FILES_FREE = 22; | | | |
| /// const FATTR4_FILES_TOTAL = 23; | | | |
| /// const FATTR4_FS_LOCATIONS = 24; | | | |
| /// const FATTR4_HIDDEN = 25; | | | |
| /// const FATTR4_HOMOGENEOUS = 26; | | | |
| /// const FATTR4_MAXFILESIZE = 27; | | | |
| /// const FATTR4_MAXLINK = 28; | | | |
| /// const FATTR4_MAXNAME = 29; | | | |
| /// const FATTR4_MAXREAD = 30; | | | |
| /// const FATTR4_MAXWRITE = 31; | | | |
| /// const FATTR4_MIMETYPE = 32; | | | |
| /// const FATTR4_MODE = 33; | | | |
| /// const FATTR4_NO_TRUNC = 34; | | | |
| /// const FATTR4_NUMLINKS = 35; | | | |
| /// const FATTR4_OWNER = 36; | | | |
| /// const FATTR4_OWNER_GROUP = 37; | | | |
| /// const FATTR4_QUOTA_AVAIL_HARD = 38; | | | |
| /// const FATTR4_QUOTA_AVAIL_SOFT = 39; | | | |
| /// const FATTR4_QUOTA_USED = 40; | | | |
| /// const FATTR4_RAWDEV = 41; | | | |
| /// const FATTR4_SPACE_AVAIL = 42; | | | |
| /// const FATTR4_SPACE_FREE = 43; | | | |
| /// const FATTR4_SPACE_TOTAL = 44; | | | |
| /// const FATTR4_SPACE_USED = 45; | | | |
| /// const FATTR4_SYSTEM = 46; | | | |
| /// const FATTR4_TIME_ACCESS = 47; | | | |
| /// const FATTR4_TIME_ACCESS_SET = 48; | | | |
| /// const FATTR4_TIME_BACKUP = 49; | | | |
| /// const FATTR4_TIME_CREATE = 50; | | | |
| /// const FATTR4_TIME_DELTA = 51; | | | |
| /// const FATTR4_TIME_METADATA = 52; | | | |
| /// const FATTR4_TIME_MODIFY = 53; | | | |
| /// const FATTR4_TIME_MODIFY_SET = 54; | | | |
| /// const FATTR4_MOUNTED_ON_FILEID = 55; | | | |
| /// | | | |
| /// /* | | | |
| /// * File attribute container | | | |
| /// */ | | | |
| /// struct fattr4 { | | | |
| /// bitmap4 attrmask; | | | |
| /// attrlist4 attr_vals; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Change info for the client | | | |
| /// */ | | | |
| /// struct change_info4 { | | | |
| /// bool atomic; | | | |
| /// changeid4 before; | | | |
| /// changeid4 after; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// struct clientaddr4 { | | | |
| /// /* see struct rpcb in RFC 1833 */ | | | |
| /// string r_netid<>; /* network id */ | | | |
| /// string r_addr<>; /* universal address */ | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Callback program info as provided by the client | | | |
| /// */ | | | |
| /// struct cb_client4 { | | | |
| /// unsigned int cb_program; | | | |
| /// clientaddr4 cb_location; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Stateid | | | |
| /// */ | | | |
| /// struct stateid4 { | | | |
| /// uint32_t seqid; | | | |
| /// opaque other[12]; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * Client ID | | | |
| /// */ | | | |
| /// struct nfs_client_id4 { | | | |
| /// verifier4 verifier; | | | |
| /// opaque id<NFS4_OPAQUE_LIMIT>; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// struct open_owner4 { | | | |
| /// clientid4 clientid; | | | |
| /// opaque owner<NFS4_OPAQUE_LIMIT>; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// struct lock_owner4 { | | | |
| /// clientid4 clientid; | | | |
| /// opaque owner<NFS4_OPAQUE_LIMIT>; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// enum nfs_lock_type4 { | | | |
| /// READ_LT = 1, | | | |
| /// WRITE_LT = 2, | | | |
| /// READW_LT = 3, /* blocking read */ | | | |
| /// WRITEW_LT = 4 /* blocking write */ | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// const ACCESS4_READ = 0x00000001; | | | |
| /// const ACCESS4_LOOKUP = 0x00000002; | | | |
| /// const ACCESS4_MODIFY = 0x00000004; | | | |
| /// const ACCESS4_EXTEND = 0x00000008; | | | |
| /// const ACCESS4_DELETE = 0x00000010; | | | |
| /// const ACCESS4_EXECUTE = 0x00000020; | | | |
| /// | | | |
| /// struct ACCESS4args { | | | |
| /// /* CURRENT_FH: object */ | | | |
| /// uint32_t access; | | | |
| /// }; | | | |
| /// | | | |
| /// struct ACCESS4resok { | | | |
| /// uint32_t supported; | | | |
| /// uint32_t access; | | | |
| /// }; | | | |
| /// | | | |
| /// union ACCESS4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// ACCESS4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct CLOSE4args { | | | |
| /// /* CURRENT_FH: object */ | | | |
| /// seqid4 seqid; | | | |
| /// stateid4 open_stateid; | | | |
| /// }; | | | |
| /// | | | |
| /// union CLOSE4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// stateid4 open_stateid; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct COMMIT4args { | | | |
| /// /* CURRENT_FH: file */ | | | |
| /// offset4 offset; | | | |
| /// count4 count; | | | |
| /// }; | | | |
| /// | | | |
| /// struct COMMIT4resok { | | | |
| /// verifier4 writeverf; | | | |
| /// }; | | | |
| /// | | | |
| /// union COMMIT4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// COMMIT4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// union createtype4 switch (nfs_ftype4 type) { | | | |
| /// case NF4LNK: | | | |
| /// linktext4 linkdata; | | | |
| /// case NF4BLK: | | | |
| /// case NF4CHR: | | | |
| /// specdata4 devdata; | | | |
| /// case NF4SOCK: | | | |
| /// case NF4FIFO: | | | |
| /// case NF4DIR: | | | |
| /// void; | | | |
| /// default: | | | |
| /// void; /* server should return NFS4ERR_BADTYPE */ | | | |
| /// }; | | | |
| /// | | | |
| /// struct CREATE4args { | | | |
| /// /* CURRENT_FH: directory for creation */ | | | |
| /// createtype4 objtype; | | | |
| /// component4 objname; | | | |
| /// fattr4 createattrs; | | | |
| /// }; | | | |
| /// | | | |
| /// struct CREATE4resok { | | | |
| /// change_info4 cinfo; | | | |
| /// bitmap4 attrset; /* attributes set */ | | | |
| /// }; | | | |
| /// | | | |
| /// union CREATE4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// CREATE4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct DELEGPURGE4args { | | | |
| /// clientid4 clientid; | | | |
| /// }; | | | |
| /// | | | |
| /// struct DELEGPURGE4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct DELEGRETURN4args { | | | |
| /// /* CURRENT_FH: delegated file */ | | | |
| /// stateid4 deleg_stateid; | | | |
| /// }; | | | |
| /// | | | |
| /// struct DELEGRETURN4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct GETATTR4args { | | | |
| /// /* CURRENT_FH: directory or file */ | | | |
| /// bitmap4 attr_request; | | | |
| /// }; | | | |
| /// | | | |
| /// struct GETATTR4resok { | | | |
| /// fattr4 obj_attributes; | | | |
| /// }; | | | |
| /// | | | |
| /// union GETATTR4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// GETATTR4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct GETFH4resok { | | | |
| /// nfs_fh4 object; | | | |
| /// }; | | | |
| /// | | | |
| /// union GETFH4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// GETFH4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LINK4args { | | | |
| /// /* SAVED_FH: source object */ | | | |
| /// /* CURRENT_FH: target directory */ | | | |
| /// component4 newname; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LINK4resok { | | | |
| /// change_info4 cinfo; | | | |
| /// }; | | | |
| /// | | | |
| /// union LINK4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| | | | |
|
| /// LINK4resok resok4; | | The following list is not all inclusive of all changes but presents | |
| /// default: | | some of the most notable changes or additions made: | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * For LOCK, transition from open_owner to new lock_owner | | | |
| /// */ | | | |
| /// struct open_to_lock_owner4 { | | | |
| /// seqid4 open_seqid; | | | |
| /// stateid4 open_stateid; | | | |
| /// seqid4 lock_seqid; | | | |
| /// lock_owner4 lock_owner; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * For LOCK, existing lock_owner continues to request file locks | | | |
| /// */ | | | |
| /// struct exist_lock_owner4 { | | | |
| /// stateid4 lock_stateid; | | | |
| /// seqid4 lock_seqid; | | | |
| /// }; | | | |
| /// | | | |
| /// union locker4 switch (bool new_lock_owner) { | | | |
| /// case TRUE: | | | |
| /// open_to_lock_owner4 open_owner; | | | |
| /// case FALSE: | | | |
| /// exist_lock_owner4 lock_owner; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * LOCK/LOCKT/LOCKU: Record lock management | | | |
| /// */ | | | |
| /// struct LOCK4args { | | | |
| /// /* CURRENT_FH: file */ | | | |
| /// nfs_lock_type4 locktype; | | | |
| /// bool reclaim; | | | |
| /// offset4 offset; | | | |
| /// length4 length; | | | |
| /// locker4 locker; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LOCK4denied { | | | |
| /// offset4 offset; | | | |
| /// length4 length; | | | |
| /// nfs_lock_type4 locktype; | | | |
| /// lock_owner4 owner; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LOCK4resok { | | | |
| /// stateid4 lock_stateid; | | | |
| /// }; | | | |
| /// | | | |
| /// union LOCK4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// LOCK4resok resok4; | | | |
| /// case NFS4ERR_DENIED: | | | |
| /// LOCK4denied denied; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LOCKT4args { | | | |
| /// /* CURRENT_FH: file */ | | | |
| /// nfs_lock_type4 locktype; | | | |
| /// offset4 offset; | | | |
| /// length4 length; | | | |
| /// lock_owner4 owner; | | | |
| /// }; | | | |
| /// | | | |
| /// union LOCKT4res switch (nfsstat4 status) { | | | |
| /// case NFS4ERR_DENIED: | | | |
| /// LOCK4denied denied; | | | |
| /// case NFS4_OK: | | | |
| /// void; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LOCKU4args { | | | |
| /// /* CURRENT_FH: file */ | | | |
| /// nfs_lock_type4 locktype; | | | |
| /// seqid4 seqid; | | | |
| /// stateid4 lock_stateid; | | | |
| /// offset4 offset; | | | |
| /// length4 length; | | | |
| /// }; | | | |
| /// | | | |
| /// union LOCKU4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// stateid4 lock_stateid; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LOOKUP4args { | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// component4 objname; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LOOKUP4res { | | | |
| /// /* CURRENT_FH: object */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct LOOKUPP4res { | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct NVERIFY4args { | | | |
| /// /* CURRENT_FH: object */ | | | |
| /// fattr4 obj_attributes; | | | |
| /// }; | | | |
| /// | | | |
| /// struct NVERIFY4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// const OPEN4_SHARE_ACCESS_READ = 0x00000001; | | | |
| /// const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; | | | |
| /// const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; | | | |
| /// | | | |
| /// const OPEN4_SHARE_DENY_NONE = 0x00000000; | | | |
| /// const OPEN4_SHARE_DENY_READ = 0x00000001; | | | |
| /// const OPEN4_SHARE_DENY_WRITE = 0x00000002; | | | |
| /// const OPEN4_SHARE_DENY_BOTH = 0x00000003; | | | |
| /// /* | | | |
| /// * Various definitions for OPEN | | | |
| /// */ | | | |
| /// enum createmode4 { | | | |
| /// UNCHECKED4 = 0, | | | |
| /// GUARDED4 = 1, | | | |
| /// EXCLUSIVE4 = 2, | | | |
| /// }; | | | |
| /// | | | |
| /// union createhow4 switch (createmode4 mode) { | | | |
| /// case UNCHECKED4: | | | |
| /// case GUARDED4: | | | |
| /// fattr4 createattrs; | | | |
| /// case EXCLUSIVE4: | | | |
| /// verifier4 createverf; | | | |
| /// }; | | | |
| /// | | | |
| /// enum opentype4 { | | | |
| /// OPEN4_NOCREATE = 0, | | | |
| /// OPEN4_CREATE = 1 | | | |
| /// }; | | | |
| /// | | | |
| /// union openflag4 switch (opentype4 opentype) { | | | |
| /// case OPEN4_CREATE: | | | |
| /// createhow4 how; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// /* Next definitions used for OPEN delegation */ | | | |
| /// enum limit_by4 { | | | |
| /// NFS_LIMIT_SIZE = 1, | | | |
| /// NFS_LIMIT_BLOCKS = 2 | | | |
| /// /* others as needed */ | | | |
| /// }; | | | |
| /// | | | |
| /// struct nfs_modified_limit4 { | | | |
| /// uint32_t num_blocks; | | | |
| /// uint32_t bytes_per_block; | | | |
| /// }; | | | |
| /// | | | |
| /// union nfs_space_limit4 switch (limit_by4 limitby) { | | | |
| /// /* limit specified as file size */ | | | |
| /// case NFS_LIMIT_SIZE: | | | |
| /// uint64_t filesize; | | | |
| /// /* limit specified by number of blocks */ | | | |
| /// case NFS_LIMIT_BLOCKS: | | | |
| /// nfs_modified_limit4 mod_blocks; | | | |
| /// } ; | | | |
| /// | | | |
| /// enum open_delegation_type4 { | | | |
| /// OPEN_DELEGATE_NONE = 0, | | | |
| /// OPEN_DELEGATE_READ = 1, | | | |
| /// OPEN_DELEGATE_WRITE = 2 | | | |
| /// }; | | | |
| /// | | | |
| /// enum open_claim_type4 { | | | |
| /// CLAIM_NULL = 0, | | | |
| /// CLAIM_PREVIOUS = 1, | | | |
| /// CLAIM_DELEGATE_CUR = 2, | | | |
| /// CLAIM_DELEGATE_PREV = 3, | | | |
| /// }; | | | |
| /// | | | |
| /// struct open_claim_delegate_cur4 { | | | |
| /// stateid4 delegate_stateid; | | | |
| /// component4 file; | | | |
| /// }; | | | |
| /// | | | |
| /// union open_claim4 switch (open_claim_type4 claim) { | | | |
| /// /* | | | |
| /// * No special rights to file. | | | |
| /// * Ordinary OPEN of the specified file. | | | |
| /// */ | | | |
| /// case CLAIM_NULL: | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// component4 file; | | | |
| /// /* | | | |
| /// * Right to the file established by an | | | |
| /// * open previous to server reboot. File | | | |
| /// * identified by filehandle obtained at | | | |
| /// * that time rather than by name. | | | |
| /// */ | | | |
| /// case CLAIM_PREVIOUS: | | | |
| /// /* CURRENT_FH: file being reclaimed */ | | | |
| /// open_delegation_type4 delegate_type; | | | |
| /// | | | |
| /// /* | | | |
| /// * Right to file based on a delegation | | | |
| /// * granted by the server. File is | | | |
| /// * specified by name. | | | |
| /// */ | | | |
| /// case CLAIM_DELEGATE_CUR: | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// open_claim_delegate_cur4 delegate_cur_info; | | | |
| /// | | | |
| /// /* | | | |
| /// * Right to file based on a delegation | | | |
| /// * granted to a previous boot instance | | | |
| /// * of the client. File is specified by name. | | | |
| /// */ | | | |
| /// case CLAIM_DELEGATE_PREV: | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// component4 file_delegate_prev; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * OPEN: Open a file, potentially receiving an open delegation | | | |
| /// */ | | | |
| /// struct OPEN4args { | | | |
| /// seqid4 seqid; | | | |
| /// uint32_t share_access; | | | |
| /// uint32_t share_deny; | | | |
| /// open_owner4 owner; | | | |
| /// openflag4 openhow; | | | |
| /// open_claim4 claim; | | | |
| /// }; | | | |
| /// | | | |
| /// struct open_read_delegation4 { | | | |
| /// stateid4 stateid; /* Stateid for delegation*/ | | | |
| /// bool recall; /* Pre-recalled flag for | | | |
| /// delegations obtained | | | |
| /// by reclaim (CLAIM_PREVIOUS) */ | | | |
| /// | | | |
| /// nfsace4 permissions; /* Defines users who don't | | | |
| /// need an ACCESS call to | | | |
| /// open for read */ | | | |
| /// }; | | | |
| /// | | | |
| /// struct open_write_delegation4 { | | | |
| /// stateid4 stateid; /* Stateid for delegation */ | | | |
| /// bool recall; /* Pre-recalled flag for | | | |
| /// delegations obtained | | | |
| /// by reclaim | | | |
| /// (CLAIM_PREVIOUS) */ | | | |
| /// | | | |
| /// nfs_space_limit4 | | | |
| /// space_limit; /* Defines condition that | | | |
| /// the client must check to | | | |
| /// determine whether the | | | |
| /// file needs to be flushed | | | |
| /// to the server on close. */ | | | |
| /// | | | |
| /// nfsace4 permissions; /* Defines users who don't | | | |
| /// need an ACCESS call as | | | |
| /// part of a delegated | | | |
| /// open. */ | | | |
| /// }; | | | |
| /// | | | |
| /// union open_delegation4 | | | |
| /// switch (open_delegation_type4 delegation_type) { | | | |
| /// case OPEN_DELEGATE_NONE: | | | |
| /// void; | | | |
| /// case OPEN_DELEGATE_READ: | | | |
| /// open_read_delegation4 read; | | | |
| /// case OPEN_DELEGATE_WRITE: | | | |
| /// open_write_delegation4 write; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * Result flags | | | |
| /// */ | | | |
| /// | | | |
| /// /* Client must confirm open */ | | | |
| /// const OPEN4_RESULT_CONFIRM = 0x00000002; | | | |
| /// /* Type of file locking behavior at the server */ | | | |
| /// const OPEN4_RESULT_LOCKTYPE_POSIX = 0x00000004; | | | |
| /// | | | |
| /// struct OPEN4resok { | | | |
| /// stateid4 stateid; /* Stateid for open */ | | | |
| /// change_info4 cinfo; /* Directory Change Info */ | | | |
| /// uint32_t rflags; /* Result flags */ | | | |
| /// bitmap4 attrset; /* attribute set for create*/ | | | |
| /// open_delegation4 delegation; /* Info on any open | | | |
| /// delegation */ | | | |
| /// }; | | | |
| /// | | | |
| /// union OPEN4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// /* CURRENT_FH: opened file */ | | | |
| /// OPEN4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct OPENATTR4args { | | | |
| /// /* CURRENT_FH: object */ | | | |
| /// bool createdir; | | | |
| /// }; | | | |
| /// | | | |
| /// struct OPENATTR4res { | | | |
| /// /* CURRENT_FH: named attr directory */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct OPEN_CONFIRM4args { | | | |
| /// /* CURRENT_FH: opened file */ | | | |
| /// stateid4 open_stateid; | | | |
| /// seqid4 seqid; | | | |
| /// }; | | | |
| /// | | | |
| /// struct OPEN_CONFIRM4resok { | | | |
| /// stateid4 open_stateid; | | | |
| /// }; | | | |
| /// | | | |
| /// union OPEN_CONFIRM4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// OPEN_CONFIRM4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct OPEN_DOWNGRADE4args { | | | |
| /// /* CURRENT_FH: opened file */ | | | |
| /// stateid4 open_stateid; | | | |
| /// seqid4 seqid; | | | |
| /// uint32_t share_access; | | | |
| /// uint32_t share_deny; | | | |
| /// }; | | | |
| /// | | | |
| /// struct OPEN_DOWNGRADE4resok { | | | |
| /// stateid4 open_stateid; | | | |
| /// }; | | | |
| /// | | | |
| /// union OPEN_DOWNGRADE4res switch(nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// OPEN_DOWNGRADE4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct PUTFH4args { | | | |
| /// nfs_fh4 object; | | | |
| /// }; | | | |
| /// | | | |
| /// struct PUTFH4res { | | | |
| /// /* CURRENT_FH: */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct PUTPUBFH4res { | | | |
| /// /* CURRENT_FH: public fh */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct PUTROOTFH4res { | | | |
| /// /* CURRENT_FH: root fh */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct READ4args { | | | |
| /// /* CURRENT_FH: file */ | | | |
| /// stateid4 stateid; | | | |
| /// offset4 offset; | | | |
| /// count4 count; | | | |
| /// }; | | | |
| /// | | | |
| /// struct READ4resok { | | | |
| /// bool eof; | | | |
| /// opaque data<>; | | | |
| /// }; | | | |
| /// | | | |
| /// union READ4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// READ4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct READDIR4args { | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// nfs_cookie4 cookie; | | | |
| /// verifier4 cookieverf; | | | |
| /// count4 dircount; | | | |
| /// count4 maxcount; | | | |
| /// bitmap4 attr_request; | | | |
| /// }; | | | |
| /// | | | |
| /// struct entry4 { | | | |
| /// nfs_cookie4 cookie; | | | |
| /// component4 name; | | | |
| /// fattr4 attrs; | | | |
| /// entry4 *nextentry; | | | |
| /// }; | | | |
| /// | | | |
| /// struct dirlist4 { | | | |
| /// entry4 *entries; | | | |
| /// bool eof; | | | |
| /// }; | | | |
| /// | | | |
| /// struct READDIR4resok { | | | |
| /// verifier4 cookieverf; | | | |
| /// dirlist4 reply; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// union READDIR4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// READDIR4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// struct READLINK4resok { | | | |
| /// linktext4 link; | | | |
| /// }; | | | |
| /// | | | |
| /// union READLINK4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// READLINK4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct REMOVE4args { | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// component4 target; | | | |
| /// }; | | | |
| /// | | | |
| /// struct REMOVE4resok { | | | |
| /// change_info4 cinfo; | | | |
| /// }; | | | |
| /// | | | |
| /// union REMOVE4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// REMOVE4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct RENAME4args { | | | |
| /// /* SAVED_FH: source directory */ | | | |
| /// component4 oldname; | | | |
| /// /* CURRENT_FH: target directory */ | | | |
| /// component4 newname; | | | |
| /// }; | | | |
| /// | | | |
| /// struct RENAME4resok { | | | |
| /// change_info4 source_cinfo; | | | |
| /// change_info4 target_cinfo; | | | |
| /// }; | | | |
| /// | | | |
| /// union RENAME4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// RENAME4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct RENEW4args { | | | |
| /// clientid4 clientid; | | | |
| /// }; | | | |
| /// | | | |
| /// struct RENEW4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct RESTOREFH4res { | | | |
| /// /* CURRENT_FH: value of saved fh */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct SAVEFH4res { | | | |
| /// /* SAVED_FH: value of current fh */ | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct SECINFO4args { | | | |
| /// /* CURRENT_FH: directory */ | | | |
| /// component4 name; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * From RFC 2203 | | | |
| /// */ | | | |
| /// enum rpc_gss_svc_t { | | | |
| /// RPC_GSS_SVC_NONE = 1, | | | |
| /// RPC_GSS_SVC_INTEGRITY = 2, | | | |
| /// RPC_GSS_SVC_PRIVACY = 3 | | | |
| /// }; | | | |
| /// | | | |
| /// struct rpcsec_gss_info { | | | |
| /// sec_oid4 oid; | | | |
| /// qop4 qop; | | | |
| /// rpc_gss_svc_t service; | | | |
| /// }; | | | |
| /// | | | |
| /// /* RPCSEC_GSS has a value of '6' - See RFC 2203 */ | | | |
| /// union secinfo4 switch (uint32_t flavor) { | | | |
| /// case RPCSEC_GSS: | | | |
| /// rpcsec_gss_info flavor_info; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// typedef secinfo4 SECINFO4resok<>; | | | |
| /// | | | |
| /// union SECINFO4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// SECINFO4resok resok4; | | | |
| /// default: | | | |
| | | | |
|
| /// void; | | o The state model has added an open_owner4 identifier. This was | |
| /// }; | | done to accommodate Posix based clients and the model they use for | |
| /// | | file locking. For Posix clients, an open_owner4 would correspond | |
| /// struct SETATTR4args { | | to a file descriptor potentially shared amongst a set of processes | |
| /// /* CURRENT_FH: target object */ | | and the lock_owner4 identifier would correspond to a process that | |
| /// stateid4 stateid; | | is locking a file. | |
| /// fattr4 obj_attributes; | | | |
| /// }; | | | |
| /// | | | |
| /// struct SETATTR4res { | | | |
| /// nfsstat4 status; | | | |
| /// bitmap4 attrsset; | | | |
| /// }; | | | |
| /// | | | |
| /// struct SETCLIENTID4args { | | | |
| /// nfs_client_id4 client; | | | |
| /// cb_client4 callback; | | | |
| /// uint32_t callback_ident; | | | |
| /// }; | | | |
| /// | | | |
| /// struct SETCLIENTID4resok { | | | |
| /// clientid4 clientid; | | | |
| /// verifier4 setclientid_confirm; | | | |
| /// }; | | | |
| /// | | | |
| /// union SETCLIENTID4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// SETCLIENTID4resok resok4; | | | |
| /// case NFS4ERR_CLID_INUSE: | | | |
| /// clientaddr4 client_using; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct SETCLIENTID_CONFIRM4args { | | | |
| /// clientid4 clientid; | | | |
| /// verifier4 setclientid_confirm; | | | |
| /// }; | | | |
| /// | | | |
| /// struct SETCLIENTID_CONFIRM4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct VERIFY4args { | | | |
| /// /* CURRENT_FH: object */ | | | |
| /// fattr4 obj_attributes; | | | |
| /// }; | | | |
| /// | | | |
| /// struct VERIFY4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// enum stable_how4 { | | | |
| /// UNSTABLE4 = 0, | | | |
| /// DATA_SYNC4 = 1, | | | |
| /// FILE_SYNC4 = 2 | | | |
| /// }; | | | |
| /// | | | |
| /// struct WRITE4args { | | | |
| /// /* CURRENT_FH: file */ | | | |
| /// stateid4 stateid; | | | |
| /// offset4 offset; | | | |
| /// stable_how4 stable; | | | |
| /// opaque data<>; | | | |
| /// }; | | | |
| /// | | | |
| /// struct WRITE4resok { | | | |
| /// count4 count; | | | |
| /// stable_how4 committed; | | | |
| /// verifier4 writeverf; | | | |
| /// }; | | | |
| /// | | | |
| /// union WRITE4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// WRITE4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct RELEASE_LOCKOWNER4args { | | | |
| /// lock_owner4 lock_owner; | | | |
| /// }; | | | |
| /// | | | |
| /// struct RELEASE_LOCKOWNER4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// struct ILLEGAL4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * Operation arrays | | | |
| /// */ | | | |
| /// | | | |
| /// enum nfs_opnum4 { | | | |
| /// OP_ACCESS = 3, | | | |
| /// OP_CLOSE = 4, | | | |
| /// OP_COMMIT = 5, | | | |
| /// OP_CREATE = 6, | | | |
| /// OP_DELEGPURGE = 7, | | | |
| /// OP_DELEGRETURN = 8, | | | |
| /// OP_GETATTR = 9, | | | |
| /// OP_GETFH = 10, | | | |
| /// OP_LINK = 11, | | | |
| /// OP_LOCK = 12, | | | |
| /// OP_LOCKT = 13, | | | |
| /// OP_LOCKU = 14, | | | |
| /// OP_LOOKUP = 15, | | | |
| /// OP_LOOKUPP = 16, | | | |
| /// OP_NVERIFY = 17, | | | |
| /// OP_OPEN = 18, | | | |
| /// OP_OPENATTR = 19, | | | |
| /// OP_OPEN_CONFIRM = 20, | | | |
| /// OP_OPEN_DOWNGRADE = 21, | | | |
| /// OP_PUTFH = 22, | | | |
| /// OP_PUTPUBFH = 23, | | | |
| /// OP_PUTROOTFH = 24, | | | |
| /// OP_READ = 25, | | | |
| /// OP_READDIR = 26, | | | |
| /// OP_READLINK = 27, | | | |
| /// OP_REMOVE = 28, | | | |
| /// OP_RENAME = 29, | | | |
| /// OP_RENEW = 30, | | | |
| /// OP_RESTOREFH = 31, | | | |
| /// OP_SAVEFH = 32, | | | |
| /// OP_SECINFO = 33, | | | |
| /// OP_SETATTR = 34, | | | |
| /// OP_SETCLIENTID = 35, | | | |
| /// OP_SETCLIENTID_CONFIRM = 36, | | | |
| /// OP_VERIFY = 37, | | | |
| /// OP_WRITE = 38, | | | |
| /// OP_RELEASE_LOCKOWNER = 39, | | | |
| /// OP_ILLEGAL = 10044 | | | |
| /// }; | | | |
| /// | | | |
| /// union nfs_argop4 switch (nfs_opnum4 argop) { | | | |
| /// case OP_ACCESS: ACCESS4args opaccess; | | | |
| /// case OP_CLOSE: CLOSE4args opclose; | | | |
| /// case OP_COMMIT: COMMIT4args opcommit; | | | |
| /// case OP_CREATE: CREATE4args opcreate; | | | |
| /// case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; | | | |
| /// case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; | | | |
| /// case OP_GETATTR: GETATTR4args opgetattr; | | | |
| /// case OP_GETFH: void; | | | |
| /// case OP_LINK: LINK4args oplink; | | | |
| /// case OP_LOCK: LOCK4args oplock; | | | |
| /// case OP_LOCKT: LOCKT4args oplockt; | | | |
| /// case OP_LOCKU: LOCKU4args oplocku; | | | |
| /// case OP_LOOKUP: LOOKUP4args oplookup; | | | |
| /// case OP_LOOKUPP: void; | | | |
| /// case OP_NVERIFY: NVERIFY4args opnverify; | | | |
| /// case OP_OPEN: OPEN4args opopen; | | | |
| /// case OP_OPENATTR: OPENATTR4args opopenattr; | | | |
| /// case OP_OPEN_CONFIRM: OPEN_CONFIRM4args opopen_confirm; | | | |
| /// case OP_OPEN_DOWNGRADE: | | | |
| /// OPEN_DOWNGRADE4args opopen_downgrade; | | | |
| /// case OP_PUTFH: PUTFH4args opputfh; | | | |
| /// case OP_PUTPUBFH: void; | | | |
| /// case OP_PUTROOTFH: void; | | | |
| /// case OP_READ: READ4args opread; | | | |
| /// case OP_READDIR: READDIR4args opreaddir; | | | |
| /// case OP_READLINK: void; | | | |
| /// case OP_REMOVE: REMOVE4args opremove; | | | |
| /// case OP_RENAME: RENAME4args oprename; | | | |
| /// case OP_RENEW: RENEW4args oprenew; | | | |
| /// case OP_RESTOREFH: void; | | | |
| /// case OP_SAVEFH: void; | | | |
| /// case OP_SECINFO: SECINFO4args opsecinfo; | | | |
| /// case OP_SETATTR: SETATTR4args opsetattr; | | | |
| /// case OP_SETCLIENTID: SETCLIENTID4args opsetclientid; | | | |
| /// case OP_SETCLIENTID_CONFIRM: SETCLIENTID_CONFIRM4args | | | |
| /// opsetclientid_confirm; | | | |
| /// case OP_VERIFY: VERIFY4args opverify; | | | |
| /// case OP_WRITE: WRITE4args opwrite; | | | |
| /// case OP_RELEASE_LOCKOWNER: | | | |
| /// RELEASE_LOCKOWNER4args | | | |
| /// oprelease_lockowner; | | | |
| /// case OP_ILLEGAL: void; | | | |
| /// }; | | | |
| /// | | | |
| /// union nfs_resop4 switch (nfs_opnum4 resop) { | | | |
| /// case OP_ACCESS: ACCESS4res opaccess; | | | |
| /// case OP_CLOSE: CLOSE4res opclose; | | | |
| /// case OP_COMMIT: COMMIT4res opcommit; | | | |
| /// case OP_CREATE: CREATE4res opcreate; | | | |
| /// case OP_DELEGPURGE: DELEGPURGE4res opdelegpurge; | | | |
| /// case OP_DELEGRETURN: DELEGRETURN4res opdelegreturn; | | | |
| /// case OP_GETATTR: GETATTR4res opgetattr; | | | |
| /// case OP_GETFH: GETFH4res opgetfh; | | | |
| /// case OP_LINK: LINK4res oplink; | | | |
| /// case OP_LOCK: LOCK4res oplock; | | | |
| /// case OP_LOCKT: LOCKT4res oplockt; | | | |
| /// case OP_LOCKU: LOCKU4res oplocku; | | | |
| /// case OP_LOOKUP: LOOKUP4res oplookup; | | | |
| /// case OP_LOOKUPP: LOOKUPP4res oplookupp; | | | |
| /// case OP_NVERIFY: NVERIFY4res opnverify; | | | |
| /// case OP_OPEN: OPEN4res opopen; | | | |
| /// case OP_OPENATTR: OPENATTR4res opopenattr; | | | |
| /// case OP_OPEN_CONFIRM: OPEN_CONFIRM4res opopen_confirm; | | | |
| /// case OP_OPEN_DOWNGRADE: | | | |
| /// OPEN_DOWNGRADE4res | | | |
| /// opopen_downgrade; | | | |
| /// case OP_PUTFH: PUTFH4res opputfh; | | | |
| /// case OP_PUTPUBFH: PUTPUBFH4res opputpubfh; | | | |
| /// case OP_PUTROOTFH: PUTROOTFH4res opputrootfh; | | | |
| /// case OP_READ: READ4res opread; | | | |
| /// case OP_READDIR: READDIR4res opreaddir; | | | |
| /// case OP_READLINK: READLINK4res opreadlink; | | | |
| /// case OP_REMOVE: REMOVE4res opremove; | | | |
| /// case OP_RENAME: RENAME4res oprename; | | | |
| /// case OP_RENEW: RENEW4res oprenew; | | | |
| /// case OP_RESTOREFH: RESTOREFH4res oprestorefh; | | | |
| /// case OP_SAVEFH: SAVEFH4res opsavefh; | | | |
| /// case OP_SECINFO: SECINFO4res opsecinfo; | | | |
| /// case OP_SETATTR: SETATTR4res opsetattr; | | | |
| /// case OP_SETCLIENTID: SETCLIENTID4res opsetclientid; | | | |
| /// case OP_SETCLIENTID_CONFIRM: | | | |
| /// SETCLIENTID_CONFIRM4res | | | |
| /// opsetclientid_confirm; | | | |
| /// case OP_VERIFY: VERIFY4res opverify; | | | |
| /// case OP_WRITE: WRITE4res opwrite; | | | |
| /// case OP_RELEASE_LOCKOWNER: | | | |
| /// RELEASE_LOCKOWNER4res | | | |
| /// oprelease_lockowner; | | | |
| /// case OP_ILLEGAL: ILLEGAL4res opillegal; | | | |
| /// }; | | | |
| /// | | | |
| /// struct COMPOUND4args { | | | |
| /// utf8str_cs tag; | | | |
| /// uint32_t minorversion; | | | |
| /// nfs_argop4 argarray<>; | | | |
| /// }; | | | |
| /// | | | |
| /// struct COMPOUND4res { | | | |
| /// nfsstat4 status; | | | |
| /// utf8str_cs tag; | | | |
| /// nfs_resop4 resarray<>; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Remote file service routines | | | |
| /// */ | | | |
| /// program NFS4_PROGRAM { | | | |
| /// version NFS_V4 { | | | |
| /// void | | | |
| /// NFSPROC4_NULL(void) = 0; | | | |
| /// | | | |
| /// COMPOUND4res | | | |
| /// NFSPROC4_COMPOUND(COMPOUND4args) = 1; | | | |
| /// | | | |
| /// } = 4; | | | |
| /// } = 100003; | | | |
| /// | | | |
| /// /* | | | |
| /// * NFS4 Callback Procedure Definitions and Program | | | |
| /// */ | | | |
| /// struct CB_GETATTR4args { | | | |
| /// nfs_fh4 fh; | | | |
| /// bitmap4 attr_request; | | | |
| /// }; | | | |
| /// | | | |
| /// struct CB_GETATTR4resok { | | | |
| /// fattr4 obj_attributes; | | | |
| /// }; | | | |
| /// | | | |
| /// union CB_GETATTR4res switch (nfsstat4 status) { | | | |
| /// case NFS4_OK: | | | |
| /// CB_GETATTR4resok resok4; | | | |
| /// default: | | | |
| /// void; | | | |
| /// }; | | | |
| /// | | | |
| /// struct CB_RECALL4args { | | | |
| /// stateid4 stateid; | | | |
| /// bool truncate; | | | |
| /// nfs_fh4 fh; | | | |
| /// }; | | | |
| /// | | | |
| /// struct CB_RECALL4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * CB_ILLEGAL: Response for illegal operation numbers | | | |
| /// */ | | | |
| /// struct CB_ILLEGAL4res { | | | |
| /// nfsstat4 status; | | | |
| /// }; | | | |
| /// | | | |
| /// /* | | | |
| /// * Various definitions for CB_COMPOUND | | | |
| /// */ | | | |
| /// % | | | |
| /// enum nfs_cb_opnum4 { | | | |
| /// OP_CB_GETATTR = 3, | | | |
| /// OP_CB_RECALL = 4, | | | |
| /// OP_CB_ILLEGAL = 10044 | | | |
| /// }; | | | |
| /// | | | |
| /// union nfs_cb_argop4 switch (unsigned argop) { | | | |
| /// case OP_CB_GETATTR: | | | |
| /// CB_GETATTR4args opcbgetattr; | | | |
| /// case OP_CB_RECALL: | | | |
| /// CB_RECALL4args opcbrecall; | | | |
| /// case OP_CB_ILLEGAL: void; | | | |
| /// }; | | | |
| /// | | | |
| /// union nfs_cb_resop4 switch (unsigned resop) { | | | |
| /// case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr; | | | |
| /// case OP_CB_RECALL: CB_RECALL4res opcbrecall; | | | |
| /// case OP_CB_ILLEGAL: CB_ILLEGAL4res opcbillegal; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// struct CB_COMPOUND4args { | | | |
| /// utf8str_cs tag; | | | |
| /// uint32_t minorversion; | | | |
| /// uint32_t callback_ident; | | | |
| /// nfs_cb_argop4 argarray<>; | | | |
| /// }; | | | |
| /// | | | |
| /// struct CB_COMPOUND4res { | | | |
| /// nfsstat4 status; | | | |
| /// utf8str_cs tag; | | | |
| /// nfs_cb_resop4 resarray<>; | | | |
| /// }; | | | |
| /// | | | |
| /// | | | |
| /// | | | |
| /// /* | | | |
| /// * Program number is in the transient range since the client | | | |
| /// * will assign the exact transient program number and provide | | | |
| /// * that to the server via the SETCLIENTID operation. | | | |
| /// */ | | | |
| /// program NFS4_CALLBACK { | | | |
| /// version NFS_CB { | | | |
| /// void | | | |
| /// CB_NULL(void) = 0; | | | |
| /// CB_COMPOUND4res | | | |
| /// CB_COMPOUND(CB_COMPOUND4args) = 1; | | | |
| /// } = 1; | | | |
| /// } = 0x40000000; | | | |
| | | | |
|
| 2. Security Considerations | | o Clarifications and error conditions were added for the handling of | |
| | | the owner and group attributes. Since these attributes are string | |
| | | based (as opposed to the numeric uid/gid of previous versions of | |
| | | NFS), translations may not be available and hence the changes | |
| | | made. | |
| | | | |
|
| See the Security Considerations section of [3]. | | o Clarifications for the ACL and mode attributes to address | |
| | | evaluation and partial support. | |
| | | | |
|
| 3. IANA Considerations | | o For identifiers that are defined as XDR opaque, limits were set on | |
| | | their size. | |
| | | | |
|
| See the IANA Considerations section of [3]. | | o Added the mounted_on_filed attribute to allow Posix clients to | |
| | | correctly construct local mounts. | |
| | | | |
|
| 4. Normative References | | o Modified the SETCLIENTID/SETCLIENTID_CONFIRM operations to deal | |
| | | correctly with confirmation details along with adding the ability | |
| | | to specify new client callback information. Also added | |
| | | clarification of the callback information itself. | |
| | | | |
|
| [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement | | o Added a new operation LOCKOWNER_RELEASE to enable notifying the | |
| Levels", March 1997. | | server that a lock_owner4 will no longer be used by the client. | |
| | | | |
|
| [2] Eisler, M., "XDR: External Data Representation Standard", | | o RENEW operation changes to identify the client correctly and allow | |
| STD 67, RFC 4506, May 2006. | | for additional error returns. | |
| | | | |
|
| [3] Haynes, T., "NFS Version 4 Protocol", | | o Verify error return possibilities for all operations. | |
| draft-ietf-nfsv4-rfc3530bis-00 (work in progress), March 2009. | | | |
| | | o Remove use of the pathname4 data type from LOOKUP and OPEN in | |
| | | favor of having the client construct a sequence of LOOKUP | |
| | | operations to achieive the same effect. | |
| | | | |
| | | o Clarification of the internationalization issues and adoption of | |
| | | the new stringprep profile framework. | |
| | | | |
| | | 1.3. NFS Version 4 Goals | |
| | | | |
| | | The NFS version 4 protocol is a further revision of the NFS protocol | |
| | | defined already by versions 2 [12] and 3 [13]. It retains the | |
| | | essential characteristics of previous versions: design for easy | |
| | | recovery, independent of transport protocols, operating systems and | |
| | | filesystems, simplicity, and good performance. The NFS version 4 | |
| | | revision has the following goals: | |
| | | | |
| | | o Improved access and good performance on the Internet. | |
| | | | |
| | | The protocol is designed to transit firewalls easily, perform well | |
| | | where latency is high and bandwidth is low, and scale to very | |
| | | large numbers of clients per server. | |
| | | | |
| | | o Strong security with negotiation built into the protocol. | |
| | | | |
| | | The protocol builds on the work of the ONCRPC working group in | |
| | | supporting the RPCSEC_GSS protocol. Additionally, the NFS version | |
| | | 4 protocol provides a mechanism to allow clients and servers the | |
| | | ability to negotiate security and require clients and servers to | |
| | | support a minimal set of security schemes. | |
| | | | |
| | | o Good cross-platform interoperability. | |
| | | | |
| | | The protocol features a filesystem model that provides a useful, | |
| | | common set of features that does not unduly favor one filesystem | |
| | | or operating system over another. | |
| | | | |
| | | o Designed for protocol extensions. | |
| | | | |
| | | The protocol is designed to accept standard extensions that do not | |
| | | compromise backward compatibility. | |
| | | | |
| | | 1.4. Inconsistencies of this Document with Section 18 | |
| | | | |
| | | Section 18, RPC Definition File, contains the definitions in XDR | |
| | | description language of the constructs used by the protocol. Prior | |
| | | to Section 18, several of the constructs are reproduced for purposes | |
| | | of explanation. The reader is warned of the possibility of errors in | |
| | | the reproduced constructs outside of Section 18. For any part of the | |
| | | document that is inconsistent with Section 18, Section 18 is to be | |
| | | considered authoritative. | |
| | | | |
| | | 1.5. Overview of NFS version 4 Features | |
| | | | |
| | | To provide a reasonable context for the reader, the major features of | |
| | | NFS version 4 protocol will be reviewed in brief. This will be done | |
| | | to provide an appropriate context for both the reader who is familiar | |
| | | with the previous versions of the NFS protocol and the reader that is | |
| | | new to the NFS protocols. For the reader new to the NFS protocols, | |
| | | there is still a fundamental knowledge that is expected. The reader | |
| | | should be familiar with the XDR and RPC protocols as described in [3] | |
| | | and [14]. A basic knowledge of filesystems and distributed | |
| | | filesystems is expected as well. | |
| | | | |
| | | 1.5.1. RPC and Security | |
| | | | |
| | | As with previous versions of NFS, the External Data Representation | |
| | | (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS | |
| | | version 4 protocol are those defined in [3] and [14]. To meet end to | |
| | | end security requirements, the RPCSEC_GSS framework [4] will be used | |
| | | to extend the basic RPC security. With the use of RPCSEC_GSS, | |
| | | various mechanisms can be provided to offer authentication, | |
| | | integrity, and privacy to the NFS version 4 protocol. Kerberos V5 | |
| | | will be used as described in [15] to provide one security framework. | |
| | | The LIPKEY GSS-API mechanism described in [5] will be used to provide | |
| | | for the use of user password and server public key by the NFS version | |
| | | 4 protocol. With the use of RPCSEC_GSS, other mechanisms may also be | |
| | | specified and used for NFS version 4 security. | |
| | | | |
| | | To enable in-band security negotiation, the NFS version 4 protocol | |
| | | has added a new operation which provides the client a method of | |
| | | querying the server about its policies regarding which security | |
| | | mechanisms must be used for access to the server's filesystem | |
| | | resources. With this, the client can securely match the security | |
| | | mechanism that meets the policies specified at both the client and | |
| | | server. | |
| | | | |
| | | 1.5.2. Procedure and Operation Structure | |
| | | | |
| | | A significant departure from the previous versions of the NFS | |
| | | protocol is the introduction of the COMPOUND procedure. For the NFS | |
| | | version 4 protocol, there are two RPC procedures, NULL and COMPOUND. | |
| | | The COMPOUND procedure is defined in terms of operations and these | |
| | | operations correspond more closely to the traditional NFS procedures. | |
| | | | |
| | | With the use of the COMPOUND procedure, the client is able to build | |
| | | simple or complex requests. These COMPOUND requests allow for a | |
| | | reduction in the number of RPCs needed for logical filesystem | |
| | | operations. For example, without previous contact with a server a | |
| | | client will be able to read data from a file in one request by | |
| | | combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC. | |
| | | With previous versions of the NFS protocol, this type of single | |
| | | request was not possible. | |
| | | | |
| | | The model used for COMPOUND is very simple. There is no logical OR | |
| | | or ANDing of operations. The operations combined within a COMPOUND | |
| | | request are evaluated in order by the server. Once an operation | |
| | | returns a failing result, the evaluation ends and the results of all | |
| | | evaluated operations are returned to the client. | |
| | | | |
| | | The NFS version 4 protocol continues to have the client refer to a | |
| | | file or directory at the server by a "filehandle". The COMPOUND | |
| | | procedure has a method of passing a filehandle from one operation to | |
| | | another within the sequence of operations. There is a concept of a | |
| | | "current filehandle" and "saved filehandle". Most operations use the | |
| | | "current filehandle" as the filesystem object to operate upon. The | |
| | | "saved filehandle" is used as temporary filehandle storage within a | |
| | | COMPOUND procedure as well as an additional operand for certain | |
| | | operations. | |
| | | | |
| | | 1.5.3. Filesystem Model | |
| | | | |
| | | The general filesystem model used for the NFS version 4 protocol is | |
| | | the same as previous versions. The server filesystem is hierarchical | |
| | | with the regular files contained within being treated as opaque byte | |
| | | streams. In a slight departure, file and directory names are encoded | |
| | | with UTF-8 to deal with the basics of internationalization. | |
| | | | |
| | | The NFS version 4 protocol does not require a separate protocol to | |
| | | provide for the initial mapping between path name and filehandle. | |
| | | Instead of using the older MOUNT protocol for this mapping, the | |
| | | server provides a ROOT filehandle that represents the logical root or | |
| | | top of the filesystem tree provided by the server. The server | |
| | | provides multiple filesystems by gluing them together with pseudo | |
| | | filesystems. These pseudo filesystems provide for potential gaps in | |
| | | the path names between real filesystems. | |
| | | | |
| | | 1.5.3.1. Filehandle Types | |
| | | | |
| | | In previous versions of the NFS protocol, the filehandle provided by | |
| | | the server was guaranteed to be valid or persistent for the lifetime | |
| | | of the filesystem object to which it referred. For some server | |
| | | implementations, this persistence requirement has been difficult to | |
| | | meet. For the NFS version 4 protocol, this requirement has been | |
| | | relaxed by introducing another type of filehandle, volatile. With | |
| | | persistent and volatile filehandle types, the server implementation | |
| | | can match the abilities of the filesystem at the server along with | |
| | | the operating environment. The client will have knowledge of the | |
| | | type of filehandle being provided by the server and can be prepared | |
| | | to deal with the semantics of each. | |
| | | | |
| | | 1.5.3.2. Attribute Types | |
| | | | |
| | | The NFS version 4 protocol introduces three classes of filesystem or | |
| | | file attributes. Like the additional filehandle type, the | |
| | | classification of file attributes has been done to ease server | |
| | | implementations along with extending the overall functionality of the | |
| | | NFS protocol. This attribute model is structured to be extensible | |
| | | such that new attributes can be introduced in minor revisions of the | |
| | | protocol without requiring significant rework. | |
| | | | |
| | | The three classifications are: mandatory, recommended and named | |
| | | attributes. This is a significant departure from the previous | |
| | | attribute model used in the NFS protocol. Previously, the attributes | |
| | | for the filesystem and file objects were a fixed set of mainly UNIX | |
| | | attributes. If the server or client did not support a particular | |
| | | attribute, it would have to simulate the attribute the best it could. | |
| | | | |
| | | Mandatory attributes are the minimal set of file or filesystem | |
| | | attributes that must be provided by the server and must be properly | |
| | | represented by the server. Recommended attributes represent | |
| | | different filesystem types and operating environments. The | |
| | | recommended attributes will allow for better interoperability and the | |
| | | inclusion of more operating environments. The mandatory and | |
| | | recommended attribute sets are traditional file or filesystem | |
| | | attributes. The third type of attribute is the named attribute. A | |
| | | named attribute is an opaque byte stream that is associated with a | |
| | | directory or file and referred to by a string name. Named attributes | |
| | | are meant to be used by client applications as a method to associate | |
| | | application specific data with a regular file or directory. | |
| | | | |
| | | One significant addition to the recommended set of file attributes is | |
| | | the Access Control List (ACL) attribute. This attribute provides for | |
| | | directory and file access control beyond the model used in previous | |
| | | versions of the NFS protocol. The ACL definition allows for | |
| | | specification of user and group level access control. | |
| | | | |
| | | 1.5.3.3. Filesystem Replication and Migration | |
| | | | |
| | | With the use of a special file attribute, the ability to migrate or | |
| | | replicate server filesystems is enabled within the protocol. The | |
| | | filesystem locations attribute provides a method for the client to | |
| | | probe the server about the location of a filesystem. In the event of | |
| | | a migration of a filesystem, the client will receive an error when | |
| | | operating on the filesystem and it can then query as to the new file | |
| | | system location. Similar steps are used for replication, the client | |
| | | is able to query the server for the multiple available locations of a | |
| | | particular filesystem. From this information, the client can use its | |
| | | own policies to access the appropriate filesystem location. | |
| | | | |
| | | 1.5.4. OPEN and CLOSE | |
| | | | |
| | | The NFS version 4 protocol introduces OPEN and CLOSE operations. The | |
| | | OPEN operation provides a single point where file lookup, creation, | |
| | | and share semantics can be combined. The CLOSE operation also | |
| | | provides for the release of state accumulated by OPEN. | |
| | | | |
| | | 1.5.5. File locking | |
| | | | |
| | | With the NFS version 4 protocol, the support for byte range file | |
| | | locking is part of the NFS protocol. The file locking support is | |
| | | structured so that an RPC callback mechanism is not required. This | |
| | | is a departure from the previous versions of the NFS file locking | |
| | | protocol, Network Lock Manager (NLM). The state associated with file | |
| | | locks is maintained at the server under a lease-based model. The | |
| | | server defines a single lease period for all state held by a NFS | |
| | | client. If the client does not renew its lease within the defined | |
| | | period, all state associated with the client's lease may be released | |
| | | by the server. The client may renew its lease with use of the RENEW | |
| | | operation or implicitly by use of other operations (primarily READ). | |
| | | | |
| | | 1.5.6. Client Caching and Delegation | |
| | | | |
| | | The file, attribute, and directory caching for the NFS version 4 | |
| | | protocol is similar to previous versions. Attributes and directory | |
| | | information are cached for a duration determined by the client. At | |
| | | the end of a predefined timeout, the client will query the server to | |
| | | see if the related filesystem object has been updated. | |
| | | | |
| | | For file data, the client checks its cache validity when the file is | |
| | | opened. A query is sent to the server to determine if the file has | |
| | | been changed. Based on this information, the client determines if | |
| | | the data cache for the file should kept or released. Also, when the | |
| | | file is closed, any modified data is written to the server. | |
| | | | |
| | | If an application wants to serialize access to file data, file | |
| | | locking of the file data ranges in question should be used. | |
| | | | |
| | | The major addition to NFS version 4 in the area of caching is the | |
| | | ability of the server to delegate certain responsibilities to the | |
| | | client. When the server grants a delegation for a file to a client, | |
| | | the client is guaranteed certain semantics with respect to the | |
| | | sharing of that file with other clients. At OPEN, the server may | |
| | | provide the client either a read or write delegation for the file. | |
| | | If the client is granted a read delegation, it is assured that no | |
| | | other client has the ability to write to the file for the duration of | |
| | | the delegation. If the client is granted a write delegation, the | |
| | | client is assured that no other client has read or write access to | |
| | | the file. | |
| | | | |
| | | Delegations can be recalled by the server. If another client | |
| | | requests access to the file in such a way that the access conflicts | |
| | | with the granted delegation, the server is able to notify the initial | |
| | | client and recall the delegation. This requires that a callback path | |
| | | exist between the server and client. If this callback path does not | |
| | | exist, then delegations can not be granted. The essence of a | |
| | | delegation is that it allows the client to locally service operations | |
| | | such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate | |
| | | interaction with the server. | |
| | | | |
| | | 1.6. General Definitions | |
| | | | |
| | | The following definitions are provided for the purpose of providing | |
| | | an appropriate context for the reader. | |
| | | | |
| | | Client The "client" is the entity that accesses the NFS server's | |
| | | resources. The client may be an application which contains the | |
| | | logic to access the NFS server directly. The client may also be | |
| | | the traditional operating system client remote filesystem services | |
| | | for a set of applications. | |
| | | | |
| | | In the case of file locking the client is the entity that | |
| | | maintains a set of locks on behalf of one or more applications. | |
| | | This client is responsible for crash or failure recovery for those | |
| | | locks it manages. | |
| | | | |
| | | Note that multiple clients may share the same transport and | |
| | | multiple clients may exist on the same network node. | |
| | | | |
| | | Clientid A 64-bit quantity used as a unique, short-hand reference to | |
| | | a client supplied Verifier and ID. The server is responsible for | |
| | | supplying the Clientid. | |
| | | | |
| | | Lease An interval of time defined by the server for which the client | |
| | | is irrevocably granted a lock. At the end of a lease period the | |
| | | lock may be revoked if the lease has not been extended. The lock | |
| | | must be revoked if a conflicting lock has been granted after the | |
| | | lease interval. | |
| | | | |
| | | All leases granted by a server have the same fixed interval. Note | |
| | | that the fixed interval was chosen to alleviate the expense a | |
| | | server would have in maintaining state about variable length | |
| | | leases across server failures. | |
| | | | |
| | | Lock The term "lock" is used to refer to both record (byte-range) | |
| | | locks as well as share reservations unless specifically stated | |
| | | otherwise. | |
| | | | |
| | | Server The "Server" is the entity responsible for coordinating | |
| | | client access to a set of filesystems. | |
| | | | |
| | | Stable Storage NFS version 4 servers must be able to recover without | |
| | | data loss from multiple power failures (including cascading power | |
| | | failures, that is, several power failures in quick succession), | |
| | | operating system failures, and hardware failure of components | |
| | | other than the storage medium itself (for example, disk, | |
| | | nonvolatile RAM). | |
| | | | |
| | | Some examples of stable storage that are allowable for an NFS | |
| | | server include: | |
| | | | |
| | | 1. Media commit of data, that is, the modified data has been | |
| | | successfully written to the disk media, for example, the disk | |
| | | platter. | |
| | | | |
| | | 2. An immediate reply disk drive with battery-backed on-drive | |
| | | intermediate storage or uninterruptible power system (UPS). | |
| | | | |
| | | 3. Server commit of data with battery-backed intermediate storage | |
| | | and recovery software. | |
| | | | |
| | | 4. Cache commit with uninterruptible power system (UPS) and | |
| | | recovery software. | |
| | | | |
| | | Stateid A 128-bit quantity returned by a server that uniquely | |
| | | defines the open and locking state provided by the server for a | |
| | | specific open or lock owner for a specific file. | |
| | | | |
| | | Stateids composed of all bits 0 or all bits 1 have special meaning | |
| | | and are reserved values. | |
| | | | |
| | | Verifier A 64-bit quantity generated by the client that the server | |
| | | can use to determine if the client has restarted and lost all | |
| | | previous lock state. | |
| | | | |
| | | 2. Protocol Data Types | |
| | | | |
| | | The syntax and semantics to describe the data types of the NFS | |
| | | version 4 protocol are defined in the XDR [14] and RPC [3] documents. | |
| | | The next sections build upon the XDR data types to define types and | |
| | | structures specific to this protocol. | |
| | | | |
| | | 2.1. Basic Data Types | |
| | | | |
| | | These are the base NFSv4 data types. | |
| | | | |
| | | +---------------+---------------------------------------------------+ | |
| | | | Data Type | Definition | | |
| | | +---------------+---------------------------------------------------+ | |
| | | | int32_t | typedef int int32_t; | | |
| | | | uint32_t | typedef unsigned int uint32_t; | | |
| | | | int64_t | typedef hyper int64_t; | | |
| | | | uint64_t | typedef unsigned hyper uint64_t; | | |
| | | | attrlist4 | typedef opaque attrlist4<>; | | |
| | | | | Used for file/directory attributes. | | |
| | | | bitmap4 | typedef uint32_t bitmap4<>; | | |
| | | | | Used in attribute array encoding. | | |
| | | | changeid4 | typedef uint64_t changeid4; | | |
| | | | | Used in the definition of change_info4. | | |
| | | | clientid4 | typedef uint64_t clientid4; | | |
| | | | | Shorthand reference to client identification. | | |
| | | | count4 | typedef uint32_t count4; | | |
| | | | | Various count parameters (READ, WRITE, COMMIT). | | |
| | | | length4 | typedef uint64_t length4; | | |
| | | | | Describes LOCK lengths. | | |
| | | | mode4 | typedef uint32_t mode4; | | |
| | | | | Mode attribute data type. | | |
| | | | nfs_cookie4 | typedef uint64_t nfs_cookie4; | | |
| | | | | Opaque cookie value for READDIR. | | |
| | | | nfs_fh4 | typedef opaque nfs_fh4<NFS4_FHSIZE>; | | |
| | | | | Filehandle definition. | | |
| | | | nfs_ftype4 | enum nfs_ftype4; | | |
| | | | | Various defined file types. | | |
| | | | nfsstat4 | enum nfsstat4; | | |
| | | | | Return value for operations. | | |
| | | | offset4 | typedef uint64_t offset4; | | |
| | | | | Various offset designations (READ, WRITE, LOCK, | | |
| | | | | COMMIT). | | |
| | | | qop4 | typedef uint32_t qop4; | | |
| | | | | Quality of protection designation in SECINFO. | | |
| | | | sec_oid4 | typedef opaque sec_oid4<>; | | |
| | | | | Security Object Identifier. The sec_oid4 data | | |
| | | | | type is not really opaque. Instead it contains an | | |
| | | | | ASN.1 OBJECT IDENTIFIER as used by GSS-API in the | | |
| | | | | mech_type argument to GSS_Init_sec_context. See | | |
| | | | | [6] for details. | | |
| | | | seqid4 | typedef uint32_t seqid4; | | |
| | | | | Sequence identifier used for file locking. | | |
| | | | utf8string | typedef opaque utf8string<>; | | |
| | | | | UTF-8 encoding for strings. | | |
| | | | utf8str_cis | typedef utf8string utf8str_cis; | | |
| | | | | Case-insensitive UTF-8 string. | | |
| | | | utf8str_cs | typedef utf8string utf8str_cs; | | |
| | | | | Case-sensitive UTF-8 string. | | |
| | | | utf8str_mixed | typedef utf8string utf8str_mixed; | | |
| | | | | UTF-8 strings with a case sensitive prefix and a | | |
| | | | | case insensitive suffix. | | |
| | | | component4 | typedef utf8str_cs component4; | | |
| | | | | Represents path name components. | | |
| | | | linktext4 | typedef utf8str_cs linktext4; | | |
| | | | | Symbolic link contents. | | |
| | | | pathname4 | typedef component4 pathname4<>; | | |
| | | | | Represents path name for fs_locations. | | |
| | | | nfs_lockid4 | typedef uint64_t nfs_lockid4; | | |
| | | | verifier4 | typedef opaque verifier4[NFS4_VERIFIER_SIZE]; | | |
| | | | | Verifier used for various operations (COMMIT, | | |
| | | | | CREATE, EXCHANGE_ID, OPEN, READDIR, WRITE) | | |
| | | | | NFS4_VERIFIER_SIZE is defined as 8. | | |
| | | +---------------+---------------------------------------------------+ | |
| | | | |
| | | End of Base Data Types | |
| | | | |
| | | Table 1 | |
| | | | |
| | | 2.2. Structured Data Types | |
| | | | |
| | | 2.2.1. nfstime4 | |
| | | | |
| | | struct nfstime4 { | |
| | | int64_t seconds; | |
| | | uint32_t nseconds; | |
| | | }; | |
| | | | |
| | | The nfstime4 structure gives the number of seconds and nanoseconds | |
| | | since midnight or 0 hour January 1, 1970 Coordinated Universal Time | |
| | | (UTC). Values greater than zero for the seconds field denote dates | |
| | | after the 0 hour January 1, 1970. Values less than zero for the | |
| | | seconds field denote dates before the 0 hour January 1, 1970. In | |
| | | both cases, the nseconds field is to be added to the seconds field | |
| | | for the final time representation. For example, if the time to be | |
| | | represented is one-half second before 0 hour January 1, 1970, the | |
| | | seconds field would have a value of negative one (-1) and the | |
| | | nseconds fields would have a value of one-half second (500000000). | |
| | | Values greater than 999,999,999 for nseconds are considered invalid. | |
| | | | |
| | | This data type is used to pass time and date information. A server | |
| | | converts to and from its local representation of time when processing | |
| | | time values, preserving as much accuracy as possible. If the | |
| | | precision of timestamps stored for a filesystem object is less than | |
| | | defined, loss of precision can occur. An adjunct time maintenance | |
| | | protocol is recommended to reduce client and server time skew. | |
| | | | |
| | | 2.2.2. time_how4 | |
| | | | |
| | | enum time_how4 { | |
| | | SET_TO_SERVER_TIME4 = 0, | |
| | | SET_TO_CLIENT_TIME4 = 1 | |
| | | }; | |
| | | | |
| | | 2.2.3. settime4 | |
| | | | |
| | | union settime4 switch (time_how4 set_it) { | |
| | | case SET_TO_CLIENT_TIME4: | |
| | | nfstime4 time; | |
| | | default: | |
| | | void; | |
| | | }; | |
| | | | |
| | | The above definitions are used as the attribute definitions to set | |
| | | time values. If set_it is SET_TO_SERVER_TIME4, then the server uses | |
| | | its local representation of time for the time value. | |
| | | | |
| | | 2.2.4. specdata4 | |
| | | | |
| | | struct specdata4 { | |
| | | uint32_t specdata1; /* major device number */ | |
| | | uint32_t specdata2; /* minor device number */ | |
| | | }; | |
| | | | |
| | | This data type represents additional information for the device file | |
| | | types NF4CHR and NF4BLK. | |
| | | | |
| | | 2.2.5. fsid4 | |
| | | | |
| | | struct fsid4 { | |
| | | uint64_t major; | |
| | | uint64_t minor; | |
| | | }; | |
| | | | |
| | | This type is the filesystem identifier that is used as a mandatory | |
| | | attribute. | |
| | | | |
| | | 2.2.6. fs_location4 | |
| | | | |
| | | struct fs_location4 { | |
| | | utf8str_cis server<>; | |
| | | pathname4 rootpath; | |
| | | }; | |
| | | | |
| | | 2.2.7. fs_locations4 | |
| | | | |
| | | struct fs_locations4 { | |
| | | pathname4 fs_root; | |
| | | fs_location4 locations<>; | |
| | | }; | |
| | | | |
| | | The fs_location4 and fs_locations4 data types are used for the | |
| | | fs_locations recommended attribute which is used for migration and | |
| | | replication support. | |
| | | | |
| | | 2.2.8. fattr4 | |
| | | | |
| | | struct fattr4 { | |
| | | bitmap4 attrmask; | |
| | | attrlist4 attr_vals; | |
| | | }; | |
| | | | |
| | | The fattr4 structure is used to represent file and directory | |
| | | attributes. | |
| | | | |
| | | The bitmap is a counted array of 32 bit integers used to contain bit | |
| | | values. The position of the integer in the array that contains bit n | |
| | | can be computed from the expression (n / 32) and its bit within that | |
| | | integer is (n mod 32). | |
| | | | |
| | | 0 1 | |
| | | +-----------+-----------+-----------+-- | |
| | | | count | 31 .. 0 | 63 .. 32 | | |
| | | +-----------+-----------+-----------+-- | |
| | | | |
| | | 2.2.9. change_info4 | |
| | | | |
| | | struct change_info4 { | |
| | | bool atomic; | |
| | | changeid4 before; | |
| | | changeid4 after; | |
| | | }; | |
| | | | |
| | | This structure is used with the CREATE, LINK, REMOVE, RENAME | |
| | | operations to let the client know the value of the change attribute | |
| | | for the directory in which the target filesystem object resides. | |
| | | | |
| | | 2.2.10. clientaddr4 | |
| | | | |
| | | struct clientaddr4 { | |
| | | /* see struct rpcb in RFC 1833 */ | |
| | | string r_netid<>; /* network id */ | |
| | | string r_addr<>; /* universal address */ | |
| | | }; | |
| | | | |
| | | The clientaddr4 structure is used as part of the SETCLIENTID | |
| | | operation to either specify the address of the client that is using a | |
| | | clientid or as part of the callback registration. The r_netid and | |
| | | r_addr fields are specified in [16], but they are underspecified in | |
| | | [16] as far as what they should look like for specific protocols. | |
| | | | |
| | | For TCP over IPv4 and for UDP over IPv4, the format of r_addr is the | |
| | | US-ASCII string: | |
| | | | |
| | | h1.h2.h3.h4.p1.p2 | |
| | | | |
| | | The prefix, "h1.h2.h3.h4", is the standard textual form for | |
| | | representing an IPv4 address, which is always four octets long. | |
| | | Assuming big-endian ordering, h1, h2, h3, and h4, are respectively, | |
| | | the first through fourth octets each converted to ASCII-decimal. | |
| | | Assuming big-endian ordering, p1 and p2 are, respectively, the first | |
| | | and second octets each converted to ASCII-decimal. For example, if a | |
| | | host, in big-endian order, has an address of 0x0A010307 and there is | |
| | | a service listening on, in big endian order, port 0x020F (decimal | |
| | | 527), then the complete universal address is "10.1.3.7.2.15". | |
| | | | |
| | | For TCP over IPv4 the value of r_netid is the string "tcp". For UDP | |
| | | over IPv4 the value of r_netid is the string "udp". | |
| | | | |
| | | For TCP over IPv6 and for UDP over IPv6, the format of r_addr is the | |
| | | US-ASCII string: | |
| | | | |
| | | x1:x2:x3:x4:x5:x6:x7:x8.p1.p2 | |
| | | | |
| | | The suffix "p1.p2" is the service port, and is computed the same way | |
| | | as with universal addresses for TCP and UDP over IPv4. The prefix, | |
| | | "x1:x2:x3:x4:x5:x6:x7:x8", is the standard textual form for | |
| | | representing an IPv6 address as defined in Section 2.2 of [17]. | |
| | | Additionally, the two alternative forms specified in Section 2.2 of | |
| | | [17] are also acceptable. | |
| | | | |
| | | For TCP over IPv6 the value of r_netid is the string "tcp6". For UDP | |
| | | over IPv6 the value of r_netid is the string "udp6". | |
| | | | |
| | | 2.2.11. cb_client4 | |
| | | | |
| | | struct cb_client4 { | |
| | | unsigned int cb_program; | |
| | | clientaddr4 cb_location; | |
| | | }; | |
| | | | |
| | | This structure is used by the client to inform the server of its call | |
| | | back address; includes the program number and client address. | |
| | | | |
| | | 2.2.12. nfs_client_id4 | |
| | | | |
| | | struct nfs_client_id4 { | |
| | | verifier4 verifier; | |
| | | opaque id<NFS4_OPAQUE_LIMIT>; | |
| | | }; | |
| | | | |
| | | This structure is part of the arguments to the SETCLIENTID operation. | |
| | | NFS4_OPAQUE_LIMIT is defined as 1024. | |
| | | | |
| | | 2.2.13. open_owner4 | |
| | | | |
| | | struct open_owner4 { | |
| | | clientid4 clientid; | |
| | | opaque owner<NFS4_OPAQUE_LIMIT>; | |
| | | }; | |
| | | | |
| | | This structure is used to identify the owner of open state. | |
| | | NFS4_OPAQUE_LIMIT is defined as 1024. | |
| | | | |
| | | 2.2.14. lock_owner4 | |
| | | | |
| | | struct lock_owner4 { | |
| | | clientid4 clientid; | |
| | | opaque owner<NFS4_OPAQUE_LIMIT>; | |
| | | }; | |
| | | | |
| | | This structure is used to identify the owner of file locking state. | |
| | | NFS4_OPAQUE_LIMIT is defined as 1024. | |
| | | | |
| | | 2.2.15. open_to_lock_owner4 | |
| | | | |
| | | struct open_to_lock_owner4 { | |
| | | seqid4 open_seqid; | |
| | | stateid4 open_stateid; | |
| | | seqid4 lock_seqid; | |
| | | lock_owner4 lock_owner; | |
| | | }; | |
| | | | |
| | | This structure is used for the first LOCK operation done for an | |
| | | open_owner4. It provides both the open_stateid and lock_owner such | |
| | | that the transition is made from a valid open_stateid sequence to | |
| | | that of the new lock_stateid sequence. Using this mechanism avoids | |
| | | the confirmation of the lock_owner/lock_seqid pair since it is tied | |
| | | to established state in the form of the open_stateid/open_seqid. | |
| | | | |
| | | 2.2.16. stateid4 | |
| | | | |
| | | struct stateid4 { | |
| | | uint32_t seqid; | |
| | | opaque other[12]; | |
| | | }; | |
| | | | |
| | | This structure is used for the various state sharing mechanisms | |
| | | between the client and server. For the client, this data structure | |
| | | is read-only. The starting value of the seqid field is undefined. | |
| | | The server is required to increment the seqid field monotonically at | |
| | | each transition of the stateid. This is important since the client | |
| | | will inspect the seqid in OPEN stateids to determine the order of | |
| | | OPEN processing done by the server. | |
| | | | |
| | | 3. RPC and Security Flavor | |
| | | | |
| | | The NFS version 4 protocol is a Remote Procedure Call (RPC) | |
| | | application that uses RPC version 2 and the corresponding eXternal | |
| | | Data Representation (XDR) as defined in [3] and [14]. The RPCSEC_GSS | |
| | | security flavor as defined in [4] MUST be used as the mechanism to | |
| | | deliver stronger security for the NFS version 4 protocol. | |
| | | | |
| | | 3.1. Ports and Transports | |
| | | | |
| | | Historically, NFS version 2 and version 3 servers have resided on | |
| | | port 2049. The registered port 2049 [18] for the NFS protocol should | |
| | | be the default configuration. Using the registered port for NFS | |
| | | services means the NFS client will not need to use the RPC binding | |
| | | protocols as described in [16]; this will allow NFS to transit | |
| | | firewalls. | |
| | | | |
| | | Where an NFS version 4 implementation supports operation over the IP | |
| | | network protocol, the supported transports between NFS and IP MUST be | |
| | | among the IETF-approved congestion control transport protocols, which | |
| | | include TCP and SCTP. To enhance the possibilities for | |
| | | interoperability, an NFS version 4 implementation MUST support | |
| | | operation over the TCP transport protocol, at least until such time | |
| | | as a standards track RFC revises this requirement to use a different | |
| | | IETF-approved congestion control transport protocol. | |
| | | | |
| | | If TCP is used as the transport, the client and server SHOULD use | |
| | | persistent connections. This will prevent the weakening of TCP's | |
| | | congestion control via short lived connections and will improve | |
| | | performance for the WAN environment by eliminating the need for SYN | |
| | | handshakes. | |
| | | | |
| | | As noted in the Security Considerations section, the authentication | |
| | | model for NFS version 4 has moved from machine-based to principal- | |
| | | based. However, this modification of the authentication model does | |
| | | not imply a technical requirement to move the TCP connection | |
| | | management model from whole machine-based to one based on a per user | |
| | | model. In particular, NFS over TCP client implementations have | |
| | | traditionally multiplexed traffic for multiple users over a common | |
| | | TCP connection between an NFS client and server. This has been true, | |
| | | regardless whether the NFS client is using AUTH_SYS, AUTH_DH, | |
| | | RPCSEC_GSS or any other flavor. Similarly, NFS over TCP server | |
| | | implementations have assumed such a model and thus scale the | |
| | | implementation of TCP connection management in proportion to the | |
| | | number of expected client machines. It is intended that NFS version | |
| | | 4 will not modify this connection management model. NFS version 4 | |
| | | clients that violate this assumption can expect scaling issues on the | |
| | | server and hence reduced service. | |
| | | | |
| | | Note that for various timers, the client and server should avoid | |
| | | inadvertent synchronization of those timers. For further discussion | |
| | | of the general issue refer to [19]. | |
| | | | |
| | | 3.1.1. Client Retransmission Behavior | |
| | | | |
| | | When processing a request received over a reliable transport such as | |
| | | TCP, the NFS version 4 server MUST NOT silently drop the request, | |
| | | except if the transport connection has been broken. Given such a | |
| | | contract between NFS version 4 clients and servers, clients MUST NOT | |
| | | retry a request unless one or both of the following are true: | |
| | | | |
| | | o The transport connection has been broken | |
| | | | |
| | | o The procedure being retried is the NULL procedure | |
| | | | |
| | | Since reliable transports, such as TCP, do not always synchronously | |
| | | inform a peer when the other peer has broken the connection (for | |
| | | example, when an NFS server reboots), the NFS version 4 client may | |
| | | want to actively "probe" the connection to see if has been broken. | |
| | | Use of the NULL procedure is one recommended way to do so. So, when | |
| | | a client experiences a remote procedure call timeout (of some | |
| | | arbitrary implementation specific amount), rather than retrying the | |
| | | remote procedure call, it could instead issue a NULL procedure call | |
| | | to the server. If the server has died, the transport connection | |
| | | break will eventually be indicated to the NFS version 4 client. The | |
| | | client can then reconnect, and then retry the original request. If | |
| | | the NULL procedure call gets a response, the connection has not | |
| | | broken. The client can decide to wait longer for the original | |
| | | request's response, or it can break the transport connection and | |
| | | reconnect before re-sending the original request. | |
| | | | |
| | | For callbacks from the server to the client, the same rules apply, | |
| | | but the server doing the callback becomes the client, and the client | |
| | | receiving the callback becomes the server. | |
| | | | |
| | | 3.2. Security Flavors | |
| | | | |
| | | Traditional RPC implementations have included AUTH_NONE, AUTH_SYS, | |
| | | AUTH_DH, and AUTH_KRB4 as security flavors. With [4] an additional | |
| | | security flavor of RPCSEC_GSS has been introduced which uses the | |
| | | functionality of GSS-API [6]. This allows for the use of various | |
| | | security mechanisms by the RPC layer without the additional | |
| | | implementation overhead of adding RPC security flavors. For NFS | |
| | | version 4, the RPCSEC_GSS security flavor MUST be used to enable the | |
| | | mandatory security mechanism. Other flavors, such as, AUTH_NONE, | |
| | | AUTH_SYS, and AUTH_DH MAY be implemented as well. | |
| | | | |
| | | 3.2.1. Security mechanisms for NFS version 4 | |
| | | | |
| | | The use of RPCSEC_GSS requires selection of: mechanism, quality of | |
| | | protection, and service (authentication, integrity, privacy). The | |
| | | remainder of this document will refer to these three parameters of | |
| | | the RPCSEC_GSS security as the security triple. | |
| | | | |
| | | 3.2.1.1. Kerberos V5 as a security triple | |
| | | | |
| | | The Kerberos V5 GSS-API mechanism as described in [15] MUST be | |
| | | implemented and provide the following security triples. | |
| | | | |
| | | column descriptions: | |
| | | | |
| | | 1 == number of pseudo flavor | |
| | | 2 == name of pseudo flavor | |
| | | 3 == mechanism's OID | |
| | | 4 == mechanism's algorithm(s) | |
| | | 5 == RPCSEC_GSS service | |
| | | | |
| | | 1 2 3 4 5 | |
| | | -------------------------------------------------------------------- | |
| | | 390003 krb5 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_none | |
| | | 390004 krb5i 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_integrity | |
| | | 390005 krb5p 1.2.840.113554.1.2.2 DES MAC MD5 rpc_gss_svc_privacy | |
| | | for integrity, | |
| | | and 56 bit DES | |
| | | for privacy. | |
| | | | |
| | | Note that the pseudo flavor is presented here as a mapping aid to the | |
| | | implementor. Because this NFS protocol includes a method to | |
| | | negotiate security and it understands the GSS-API mechanism, the | |
| | | pseudo flavor is not needed. The pseudo flavor is needed for NFS | |
| | | version 3 since the security negotiation is done via the MOUNT | |
| | | protocol. | |
| | | | |
| | | For a discussion of NFS' use of RPCSEC_GSS and Kerberos V5, please | |
| | | see [20]. | |
| | | | |
| | | Users and implementors are warned that 56 bit DES is no longer | |
| | | considered state of the art in terms of resistance to brute force | |
| | | attacks. Once a revision to [15] is available that adds support for | |
| | | AES, implementors are urged to incorporate AES into their NFSv4 over | |
| | | Kerberos V5 protocol stacks, and users are similarly urged to migrate | |
| | | to the use of AES. | |
| | | | |
| | | 3.2.1.2. LIPKEY as a security triple | |
| | | | |
| | | The LIPKEY GSS-API mechanism as described in [5] MAY be implemented | |
| | | and provide the following security triples. The definition of the | |
| | | columns matches the previous subsection "Kerberos V5 as security | |
| | | triple". | |
| | | | |
| | | 1 2 3 4 5 | |
| | | -------------------------------------------------------------------- | |
| | | 390006 lipkey 1.3.6.1.5.5.9 negotiated rpc_gss_svc_none | |
| | | 390007 lipkey-i 1.3.6.1.5.5.9 negotiated rpc_gss_svc_integrity | |
| | | 390008 lipkey-p 1.3.6.1.5.5.9 negotiated rpc_gss_svc_privacy | |
| | | | |
| | | The mechanism algorithm is listed as "negotiated". This is because | |
| | | LIPKEY is layered on SPKM-3 and in SPKM-3 [5] the confidentiality and | |
| | | integrity algorithms are negotiated. Since SPKM-3 specifies HMAC-MD5 | |
| | | for integrity as MANDATORY, 128 bit cast5CBC for confidentiality for | |
| | | privacy as MANDATORY, and further specifies that HMAC-MD5 and | |
| | | cast5CBC MUST be listed first before weaker algorithms, specifying | |
| | | "negotiated" in column 4 does not impair interoperability. In the | |
| | | event an SPKM-3 peer does not support the mandatory algorithms, the | |
| | | other peer is free to accept or reject the GSS-API context creation. | |
| | | | |
| | | Because SPKM-3 negotiates the algorithms, subsequent calls to | |
| | | LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality | |
| | | of protection value of 0 (zero). See section 5.2 of [21] for an | |
| | | explanation. | |
| | | | |
| | | LIPKEY uses SPKM-3 to create a secure channel in which to pass a user | |
| | | name and password from the client to the server. Once the user name | |
| | | and password have been accepted by the server, calls to the LIPKEY | |
| | | context are redirected to the SPKM-3 context. See [5] for more | |
| | | details. | |
| | | | |
| | | 3.2.1.3. SPKM-3 as a security triple | |
| | | | |
| | | The SPKM-3 GSS-API mechanism as described in [5] MAY be implemented | |
| | | and provide the following security triples. The definition of the | |
| | | columns matches the previous subsection "Kerberos V5 as security | |
| | | triple". | |
| | | | |
| | | 1 2 3 4 5 | |
| | | -------------------------------------------------------------------- | |
| | | 390009 spkm3 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_none | |
| | | 390010 spkm3i 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_integrity | |
| | | 390011 spkm3p 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_privacy | |
| | | | |
| | | For a discussion as to why the mechanism algorithm is listed as | |
| | | "negotiated", see Section 3.2.1.2 "LIPKEY as a security triple." | |
| | | | |
| | | Because SPKM-3 negotiates the algorithms, subsequent calls to SPKM- | |
| | | 3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality of | |
| | | protection value of 0 (zero). See section 5.2 of [21] for an | |
| | | explanation. | |
| | | | |
| | | Even though LIPKEY is layered over SPKM-3, SPKM-3 is specified as a | |
| | | mandatory set of triples to handle the situations where the initiator | |
| | | (the client) is anonymous or where the initiator has its own | |
| | | certificate. If the initiator is anonymous, there will not be a user | |
| | | name and password to send to the target (the server). If the | |
| | | initiator has its own certificate, then using passwords is | |
| | | superfluous. | |
| | | | |
| | | 3.3. Security Negotiation | |
| | | | |
| | | With the NFS version 4 server potentially offering multiple security | |
| | | mechanisms, the client needs a method to determine or negotiate which | |
| | | mechanism is to be used for its communication with the server. The | |
| | | NFS server may have multiple points within its filesystem name space | |
| | | that are available for use by NFS clients. In turn the NFS server | |
| | | may be configured such that each of these entry points may have | |
| | | different or multiple security mechanisms in use. | |
| | | | |
| | | The security negotiation between client and server must be done with | |
| | | a secure channel to eliminate the possibility of a third party | |
| | | intercepting the negotiation sequence and forcing the client and | |
| | | server to choose a lower level of security than required or desired. | |
| | | See Section 16 "Security Considerations" for further discussion. | |
| | | | |
| | | 3.3.1. SECINFO | |
| | | | |
| | | The new SECINFO operation will allow the client to determine, on a | |
| | | per filehandle basis, what security triple is to be used for server | |
| | | access. In general, the client will not have to use the SECINFO | |
| | | operation except during initial communication with the server or when | |
| | | the client crosses policy boundaries at the server. It is possible | |
| | | that the server's policies change during the client's interaction | |
| | | therefore forcing the client to negotiate a new security triple. | |
| | | | |
| | | 3.3.2. Security Error | |
| | | | |
| | | Based on the assumption that each NFS version 4 client and server | |
| | | must support a minimum set of security (i.e., LIPKEY, SPKM-3, and | |
| | | Kerberos-V5 all under RPCSEC_GSS), the NFS client will start its | |
| | | communication with the server with one of the minimal security | |
| | | triples. During communication with the server, the client may | |
| | | receive an NFS error of NFS4ERR_WRONGSEC. This error allows the | |
| | | server to notify the client that the security triple currently being | |
| | | used is not appropriate for access to the server's filesystem | |
| | | resources. The client is then responsible for determining what | |
| | | security triples are available at the server and choose one which is | |
| | | appropriate for the client. See Section 14.33 for the "SECINFO" | |
| | | operation for further discussion of how the client will respond to | |
| | | the NFS4ERR_WRONGSEC error and use SECINFO. | |
| | | | |
| | | 3.3.3. Callback RPC Authentication | |
| | | | |
| | | Except as noted elsewhere in this section, the callback RPC | |
| | | (described later) MUST mutually authenticate the NFS server to the | |
| | | principal that acquired the clientid (also described later), using | |
| | | the security flavor the original SETCLIENTID operation used. | |
| | | | |
| | | For AUTH_NONE, there are no principals, so this is a non-issue. | |
| | | | |
| | | AUTH_SYS has no notions of mutual authentication or a server | |
| | | principal, so the callback from the server simply uses the AUTH_SYS | |
| | | credential that the user used when he set up the delegation. | |
| | | | |
| | | For AUTH_DH, one commonly used convention is that the server uses the | |
| | | credential corresponding to this AUTH_DH principal: | |
| | | | |
| | | unix.host@domain | |
| | | | |
| | | where host and domain are variables corresponding to the name of | |
| | | server host and directory services domain in which it lives such as a | |
| | | Network Information System domain or a DNS domain. | |
| | | | |
| | | Because LIPKEY is layered over SPKM-3, it is permissible for the | |
| | | server to use SPKM-3 and not LIPKEY for the callback even if the | |
| | | client used LIPKEY for SETCLIENTID. | |
| | | | |
| | | Regardless of what security mechanism under RPCSEC_GSS is being used, | |
| | | the NFS server, MUST identify itself in GSS-API via a | |
| | | GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE | |
| | | names are of the form: | |
| | | | |
| | | service@hostname | |
| | | For NFS, the "service" element is | |
| | | | |
| | | nfs | |
| | | | |
| | | Implementations of security mechanisms will convert nfs@hostname to | |
| | | various different forms. For Kerberos V5 and LIPKEY, the following | |
| | | form is RECOMMENDED: | |
| | | | |
| | | nfs/hostname | |
| | | | |
| | | For Kerberos V5, nfs/hostname would be a server principal in the | |
| | | Kerberos Key Distribution Center database. This is the same | |
| | | principal the client acquired a GSS-API context for when it issued | |
| | | the SETCLIENTID operation, therefore, the realm name for the server | |
| | | principal must be the same for the callback as it was for the | |
| | | SETCLIENTID. | |
| | | | |
| | | For LIPKEY, this would be the username passed to the target (the NFS | |
| | | version 4 client that receives the callback). | |
| | | | |
| | | It should be noted that LIPKEY may not work for callbacks, since the | |
| | | LIPKEY client uses a user id/password. If the NFS client receiving | |
| | | the callback can authenticate the NFS server's user name/password | |
| | | pair, and if the user that the NFS server is authenticating to has a | |
| | | public key certificate, then it works. | |
| | | | |
| | | In situations where the NFS client uses LIPKEY and uses a per-host | |
| | | principal for the SETCLIENTID operation, instead of using LIPKEY for | |
| | | SETCLIENTID, it is RECOMMENDED that SPKM-3 with mutual authentication | |
| | | be used. This effectively means that the client will use a | |
| | | certificate to authenticate and identify the initiator to the target | |
| | | on the NFS server. Using SPKM-3 and not LIPKEY has the following | |
| | | advantages: | |
| | | | |
| | | o When the server does a callback, it must authenticate to the | |
| | | principal used in the SETCLIENTID. Even if LIPKEY is used, | |
| | | because LIPKEY is layered over SPKM-3, the NFS client will need to | |
| | | have a certificate that corresponds to the principal used in the | |
| | | SETCLIENTID operation. From an administrative perspective, having | |
| | | a user name, password, and certificate for both the client and | |
| | | server is redundant. | |
| | | | |
| | | o LIPKEY was intended to minimize additional infrastructure | |
| | | requirements beyond a certificate for the target, and the | |
| | | expectation is that existing password infrastructure can be | |
| | | leveraged for the initiator. In some environments, a per-host | |
| | | password does not exist yet. If certificates are used for any | |
| | | per-host principals, then additional password infrastructure is | |
| | | not needed. | |
| | | | |
| | | o In cases when a host is both an NFS client and server, it can | |
| | | share the same per-host certificate. | |
| | | | |
| | | 4. Filehandles | |
| | | | |
| | | The filehandle in the NFS protocol is a per server unique identifier | |
| | | for a filesystem 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 filesystem | |
| | | object. | |
| | | | |
| | | 4.1. Obtaining the First Filehandle | |
| | | | |
| | | The operations of the NFS protocol are defined in terms of one or | |
| | | more filehandles. Therefore, the client needs a filehandle to | |
| | | initiate communication with the server. With the NFS version 2 | |
| | | protocol [12] and the NFS version 3 protocol [13], there exists an | |
| | | ancillary protocol to obtain this first filehandle. The MOUNT | |
| | | protocol, RPC program number 100005, provides the mechanism of | |
| | | translating a string based filesystem path name to a filehandle which | |
| | | can then be used by the NFS protocols. | |
| | | | |
| | | The MOUNT protocol has deficiencies in the area of security and use | |
| | | via firewalls. This is one reason that the use of the public | |
| | | filehandle was introduced in [22] and [23]. With the use of the | |
| | | public filehandle in combination with the LOOKUP operation in the NFS | |
| | | version 2 and 3 protocols, it has been demonstrated that the MOUNT | |
| | | protocol is unnecessary for viable interaction between NFS client and | |
| | | server. | |
| | | | |
| | | Therefore, the NFS version 4 protocol will not use an ancillary | |
| | | protocol for translation from string based path names to a | |
| | | filehandle. Two special filehandles will be used as starting points | |
| | | for the NFS client. | |
| | | | |
| | | 4.1.1. Root Filehandle | |
| | | | |
| | | The first of the special filehandles is the ROOT filehandle. The | |
| | | ROOT filehandle is the "conceptual" root of the filesystem name space | |
| | | at the NFS server. The client uses or starts with the ROOT | |
| | | filehandle by employing the PUTROOTFH operation. The PUTROOTFH | |
| | | operation instructs the server to set the "current" filehandle to the | |
| | | ROOT of the server's file tree. Once this PUTROOTFH operation is | |
| | | used, the client can then traverse the entirety of the server's file | |
| | | tree with the LOOKUP operation. A complete discussion of the server | |
| | | name space is in the section "NFS Server Name Space". | |
| | | | |
| | | 4.1.2. Public Filehandle | |
| | | | |
| | | The second special filehandle is the PUBLIC filehandle. Unlike the | |
| | | ROOT filehandle, the PUBLIC filehandle may be bound or represent an | |
| | | arbitrary filesystem object at the server. The server is responsible | |
| | | for this binding. It may be that the PUBLIC filehandle and the ROOT | |
| | | filehandle refer to the same filesystem object. However, it is up to | |
| | | the administrative software at the server and the policies of the | |
| | | server administrator to define the binding of the PUBLIC filehandle | |
| | | and server filesystem object. The client may not make any | |
| | | assumptions about this binding. The client uses the PUBLIC | |
| | | filehandle via the PUTPUBFH operation. | |
| | | | |
| | | 4.2. Filehandle Types | |
| | | | |
| | | In the NFS version 2 and 3 protocols, there was one type of | |
| | | filehandle with a single set of semantics. This type of filehandle | |
| | | is termed "persistent" in NFS Version 4. The semantics of a | |
| | | persistent filehandle remain the same as before. A new type of | |
| | | filehandle introduced in NFS Version 4 is the "volatile" filehandle, | |
| | | which attempts to accommodate certain server environments. | |
| | | | |
| | | The volatile filehandle type was introduced to address server | |
| | | functionality or implementation issues which make correct | |
| | | implementation of a persistent filehandle infeasible. Some server | |
| | | environments do not provide a filesystem level invariant that can be | |
| | | used to construct a persistent filehandle. The underlying server | |
| | | filesystem may not provide the invariant or the server's filesystem | |
| | | programming interfaces may not provide access to the needed | |
| | | invariant. Volatile filehandles may ease the implementation of | |
| | | server functionality such as hierarchical storage management or | |
| | | filesystem reorganization or migration. However, the volatile | |
| | | filehandle increases the implementation burden for the client. | |
| | | | |
| | | Since the client will need to handle persistent and volatile | |
| | | filehandles differently, a file attribute is defined which may be | |
| | | used by the client to determine the filehandle types being returned | |
| | | by the server. | |
| | | | |
| | | 4.2.1. General Properties of a Filehandle | |
| | | | |
| | | The filehandle contains all the information the server needs to | |
| | | distinguish an individual file. To the client, the filehandle is | |
| | | opaque. The client stores filehandles for use in a later request and | |
| | | can compare two filehandles from the same server for equality by | |
| | | doing a byte-by-byte comparison. However, the client MUST NOT | |
| | | otherwise interpret the contents of filehandles. If two filehandles | |
| | | from the same server are equal, they MUST refer to the same file. | |
| | | Servers SHOULD try to maintain a one-to-one correspondence between | |
| | | filehandles and files but this is not required. Clients MUST use | |
| | | filehandle comparisons only to improve performance, not for correct | |
| | | behavior. All clients need to be prepared for situations in which it | |
| | | cannot be determined whether two filehandles denote the same object | |
| | | and in such cases, avoid making invalid assumptions which might cause | |
| | | incorrect behavior. Further discussion of filehandle and attribute | |
| | | comparison in the context of data caching is presented in the section | |
| | | "Data Caching and File Identity". | |
| | | | |
| | | As an example, in the case that two different path names when | |
| | | traversed at the server terminate at the same filesystem object, the | |
| | | server SHOULD return the same filehandle for each path. This can | |
| | | occur if a hard link is used to create two file names which refer to | |
| | | the same underlying file object and associated data. For example, if | |
| | | paths /a/b/c and /a/d/c refer to the same file, the server SHOULD | |
| | | return the same filehandle for both path names traversals. | |
| | | | |
| | | 4.2.2. Persistent Filehandle | |
| | | | |
| | | A persistent filehandle is defined as having a fixed value for the | |
| | | lifetime of the filesystem object to which it refers. Once the | |
| | | server creates the filehandle for a filesystem object, the server | |
| | | MUST accept the same filehandle for the object for the lifetime of | |
| | | the object. If the server restarts or reboots the NFS server must | |
| | | honor the same filehandle value as it did in the server's previous | |
| | | instantiation. Similarly, if the filesystem is migrated, the new NFS | |
| | | server must honor the same filehandle as the old NFS server. | |
| | | | |
| | | The persistent filehandle will be become stale or invalid when the | |
| | | filesystem object is removed. When the server is presented with a | |
| | | persistent filehandle that refers to a deleted object, it MUST return | |
| | | an error of NFS4ERR_STALE. A filehandle may become stale when the | |
| | | filesystem containing the object is no longer available. The file | |
| | | system may become unavailable if it exists on removable media and the | |
| | | media is no longer available at the server or the filesystem in whole | |
| | | has been destroyed or the filesystem has simply been removed from the | |
| | | server's name space (i.e., unmounted in a UNIX environment). | |
| | | | |
| | | 4.2.3. Volatile Filehandle | |
| | | | |
| | | A volatile filehandle does not share the same longevity | |
| | | characteristics of a persistent filehandle. The server may determine | |
| | | that a volatile filehandle is no longer valid at many different | |
| | | points in time. If the server can definitively determine that a | |
| | | volatile filehandle refers to an object that has been removed, the | |
| | | server should return NFS4ERR_STALE to the client (as is the case for | |
| | | persistent filehandles). In all other cases where the server | |
| | | determines that a volatile filehandle can no longer be used, it | |
| | | should return an error of NFS4ERR_FHEXPIRED. | |
| | | | |
| | | The mandatory attribute "fh_expire_type" is used by the client to | |
| | | determine what type of filehandle the server is providing for a | |
| | | particular filesystem. This attribute is a bitmask with the | |
| | | following values: | |
| | | | |
| | | FH4_PERSISTENT The value of FH4_PERSISTENT is used to indicate a | |
| | | persistent filehandle, which is valid until the object is removed | |
| | | from the filesystem. The server will not return NFS4ERR_FHEXPIRED | |
| | | for this filehandle. FH4_PERSISTENT is defined as a value in | |
| | | which none of the bits specified below are set. | |
| | | | |
| | | FH4_VOLATILE_ANY The filehandle may expire at any time, except as | |
| | | specifically excluded (i.e., FH4_NO_EXPIRE_WITH_OPEN). | |
| | | | |
| | | FH4_NOEXPIRE_WITH_OPEN May only be set when FH4_VOLATILE_ANY is set. | |
| | | If this bit is set, then the meaning of FH4_VOLATILE_ANY is | |
| | | qualified to exclude any expiration of the filehandle when it is | |
| | | open. | |
| | | | |
| | | FH4_VOL_MIGRATION The filehandle will expire as a result of | |
| | | migration. If FH4_VOL_ANY is set, FH4_VOL_MIGRATION is redundant. | |
| | | | |
| | | FH4_VOL_RENAME The filehandle will expire during rename. This | |
| | | includes a rename by the requesting client or a rename by any | |
| | | other client. If FH4_VOL_ANY is set, FH4_VOL_RENAME is redundant. | |
| | | | |
| | | Servers which provide volatile filehandles that may expire while open | |
| | | (i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if | |
| | | FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN not set), should | |
| | | deny a RENAME or REMOVE that would affect an OPEN file of any of the | |
| | | components leading to the OPEN file. In addition, the server should | |
| | | deny all RENAME or REMOVE requests during the grace period upon | |
| | | server restart. | |
| | | | |
| | | Note that the bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the | |
| | | client to determine that expiration has occurred whenever a specific | |
| | | event occurs, without an explicit filehandle expiration error from | |
| | | the server. FH4_VOL_ANY does not provide this form of information. | |
| | | In situations where the server will expire many, but not all | |
| | | filehandles upon migration (e.g., all but those that are open), | |
| | | FH4_VOLATILE_ANY (in this case with FH4_NOEXPIRE_WITH_OPEN) is a | |
| | | better choice since the client may not assume that all filehandles | |
| | | will expire when migration occurs, and it is likely that additional | |
| | | expirations will occur (as a result of file CLOSE) that are separated | |
| | | in time from the migration event itself. | |
| | | | |
| | | 4.2.4. One Method of Constructing a Volatile Filehandle | |
| | | | |
| | | A volatile filehandle, while opaque to the client could contain: | |
| | | | |
| | | [volatile bit = 1 | server boot time | slot | generation number] | |
| | | | |
| | | o slot is an index in the server volatile filehandle table | |
| | | | |
| | | o generation number is the generation number for the table entry/ | |
| | | slot | |
| | | | |
| | | When the client presents a volatile filehandle, the server makes the | |
| | | following checks, which assume that the check for the volatile bit | |
| | | has passed. If the server boot time is less than the current server | |
| | | boot time, return NFS4ERR_FHEXPIRED. If slot is out of range, return | |
| | | NFS4ERR_BADHANDLE. If the generation number does not match, return | |
| | | NFS4ERR_FHEXPIRED. | |
| | | | |
| | | When the server reboots, the table is gone (it is volatile). | |
| | | | |
| | | If volatile bit is 0, then it is a persistent filehandle with a | |
| | | different structure following it. | |
| | | | |
| | | 4.3. Client Recovery from Filehandle Expiration | |
| | | | |
| | | If possible, the client SHOULD recover from the receipt of an | |
| | | NFS4ERR_FHEXPIRED error. The client must take on additional | |
| | | responsibility so that it may prepare itself to recover from the | |
| | | expiration of a volatile filehandle. If the server returns | |
| | | persistent filehandles, the client does not need these additional | |
| | | steps. | |
| | | | |
| | | For volatile filehandles, most commonly the client will need to store | |
| | | the component names leading up to and including the filesystem object | |
| | | in question. With these names, the client should be able to recover | |
| | | by finding a filehandle in the name space that is still available or | |
| | | by starting at the root of the server's filesystem name space. | |
| | | | |
| | | If the expired filehandle refers to an object that has been removed | |
| | | from the filesystem, obviously the client will not be able to recover | |
| | | from the expired filehandle. | |
| | | | |
| | | It is also possible that the expired filehandle refers to a file that | |
| | | has been renamed. If the file was renamed by another client, again | |
| | | it is possible that the original client will not be able to recover. | |
| | | | |
| | | However, in the case that the client itself is renaming the file and | |
| | | the file is open, it is possible that the client may be able to | |
| | | recover. The client can determine the new path name based on the | |
| | | processing of the rename request. The client can then regenerate the | |
| | | new filehandle based on the new path name. The client could also use | |
| | | the compound operation mechanism to construct a set of operations | |
| | | like: | |
| | | | |
| | | RENAME A B | |
| | | LOOKUP B | |
| | | GETFH | |
| | | | |
| | | Note that the COMPOUND procedure does not provide atomicity. This | |
| | | example only reduces the overhead of recovering from an expired | |
| | | filehandle. | |
| | | | |
| | | 5. File Attributes | |
| | | | |
| | | To meet the requirements of extensibility and increased | |
| | | interoperability with non-UNIX platforms, attributes must be handled | |
| | | in a flexible manner. The NFS version 3 fattr3 structure contains a | |
| | | fixed list of attributes that not all clients and servers are able to | |
| | | support or care about. The fattr3 structure can not be extended as | |
| | | new needs arise and it provides no way to indicate non-support. With | |
| | | the NFS version 4 protocol, the client is able query what attributes | |
| | | the server supports and construct requests with only those supported | |
| | | attributes (or a subset thereof). | |
| | | | |
| | | To this end, attributes are divided into three groups: mandatory, | |
| | | recommended, and named. Both mandatory and recommended attributes | |
| | | are supported in the NFS version 4 protocol by a specific and well- | |
| | | defined encoding and are identified by number. They are requested by | |
| | | setting a bit in the bit vector sent in the GETATTR request; the | |
| | | server response includes a bit vector to list what attributes were | |
| | | returned in the response. New mandatory or recommended attributes | |
| | | may be added to the NFS protocol between major revisions by | |
| | | publishing a standards-track RFC which allocates a new attribute | |
| | | number value and defines the encoding for the attribute. See | |
| | | Section 10 "Minor Versioning" for further discussion. | |
| | | | |
| | | Named attributes are accessed by the new OPENATTR operation, which | |
| | | accesses a hidden directory of attributes associated with a file | |
| | | system object. OPENATTR takes a filehandle for the object and | |
| | | returns the filehandle for the attribute hierarchy. The filehandle | |
| | | for the named attributes is a directory object accessible by LOOKUP | |
| | | or READDIR and contains files whose names represent the named | |
| | | attributes and whose data bytes are the value of the attribute. For | |
| | | example: | |
| | | | |
| | | LOOKUP "foo" ; look up file | |
| | | GETATTR attrbits | |
| | | OPENATTR ; access foo's named attributes | |
| | | LOOKUP "x11icon" ; look up specific attribute | |
| | | READ 0,4096 ; read stream of bytes | |
| | | | |
| | | Named attributes are intended for data needed by applications rather | |
| | | than by an NFS client implementation. NFS implementors are strongly | |
| | | encouraged to define their new attributes as recommended attributes | |
| | | by bringing them to the IETF standards-track process. | |
| | | | |
| | | The set of attributes which are classified as mandatory is | |
| | | deliberately small since servers must do whatever it takes to support | |
| | | them. A server should support as many of the recommended attributes | |
| | | as possible but by their definition, the server is not required to | |
| | | support all of them. Attributes are deemed mandatory if the data is | |
| | | both needed by a large number of clients and is not otherwise | |
| | | reasonably computable by the client when support is not provided on | |
| | | the server. | |
| | | | |
| | | Note that the hidden directory returned by OPENATTR is a convenience | |
| | | for protocol processing. The client should not make any assumptions | |
| | | about the server's implementation of named attributes and whether the | |
| | | underlying filesystem at the server has a named attribute directory | |
| | | or not. Therefore, operations such as SETATTR and GETATTR on the | |
| | | named attribute directory are undefined. | |
| | | | |
| | | 5.1. Mandatory Attributes | |
| | | | |
| | | These MUST be supported by every NFS version 4 client and server in | |
| | | order to ensure a minimum level of interoperability. The server must | |
| | | store and return these attributes and the client must be able to | |
| | | function with an attribute set limited to these attributes. With | |
| | | just the mandatory attributes some client functionality may be | |
| | | impaired or limited in some ways. A client may ask for any of these | |
| | | attributes to be returned by setting a bit in the GETATTR request and | |
| | | the server must return their value. | |
| | | | |
| | | 5.2. Recommended Attributes | |
| | | | |
| | | These attributes are understood well enough to warrant support in the | |
| | | NFS version 4 protocol. However, they may not be supported on all | |
| | | clients and servers. A client may ask for any of these attributes to | |
| | | be returned by setting a bit in the GETATTR request but must handle | |
| | | the case where the server does not return them. A client may ask for | |
| | | the set of attributes the server supports and should not request | |
| | | attributes the server does not support. A server should be tolerant | |
| | | of requests for unsupported attributes and simply not return them | |
| | | rather than considering the request an error. It is expected that | |
| | | servers will support all attributes they comfortably can and only | |
| | | fail to support attributes which are difficult to support in their | |
| | | operating environments. A server should provide attributes whenever | |
| | | they don't have to "tell lies" to the client. For example, a file | |
| | | modification time should be either an accurate time or should not be | |
| | | supported by the server. This will not always be comfortable to | |
| | | clients but the client is better positioned decide whether and how to | |
| | | fabricate or construct an attribute or whether to do without the | |
| | | attribute. | |
| | | | |
| | | 5.3. Named Attributes | |
| | | | |
| | | These attributes are not supported by direct encoding in the NFS | |
| | | Version 4 protocol but are accessed by string names rather than | |
| | | numbers and correspond to an uninterpreted stream of bytes which are | |
| | | stored with the filesystem object. The name space for these | |
| | | attributes may be accessed by using the OPENATTR operation. The | |
| | | OPENATTR operation returns a filehandle for a virtual "attribute | |
| | | directory" and further perusal of the name space may be done using | |
| | | READDIR and LOOKUP operations on this filehandle. Named attributes | |
| | | may then be examined or changed by normal READ and WRITE and CREATE | |
| | | operations on the filehandles returned from READDIR and LOOKUP. | |
| | | Named attributes may have attributes. | |
| | | | |
| | | It is recommended that servers support arbitrary named attributes. A | |
| | | client should not depend on the ability to store any named attributes | |
| | | in the server's filesystem. If a server does support named | |
| | | attributes, a client which is also able to handle them should be able | |
| | | to copy a file's data and meta-data with complete transparency from | |
| | | one location to another; this would imply that names allowed for | |
| | | regular directory entries are valid for named attribute names as | |
| | | well. | |
| | | | |
| | | Names of attributes will not be controlled by this document or other | |
| | | IETF standards track documents. See Section 17 "IANA Considerations" | |
| | | for further discussion. | |
| | | | |
| | | 5.4. Classification of Attributes | |
| | | | |
| | | Each of the Mandatory and Recommended attributes can be classified in | |
| | | one of three categories: per server, per filesystem, or per | |
| | | filesystem object. Note that it is possible that some per filesystem | |
| | | attributes may vary within the filesystem. See the "homogeneous" | |
| | | attribute for its definition. Note that the attributes | |
| | | time_access_set and time_modify_set are not listed in this section | |
| | | because they are write-only attributes corresponding to time_access | |
| | | and time_modify, and are used in a special instance of SETATTR. | |
| | | | |
| | | o The per server attribute is: | |
| | | | |
| | | lease_time | |
| | | | |
| | | o The per filesystem attributes are: | |
| | | | |
| | | supp_attr, fh_expire_type, link_support, symlink_support, | |
| | | unique_handles, aclsupport, cansettime, case_insensitive, | |
| | | case_preserving, chown_restricted, files_avail, files_free, | |
| | | files_total, fs_locations, homogeneous, maxfilesize, maxname, | |
| | | maxread, maxwrite, no_trunc, space_avail, space_free, space_total, | |
| | | time_delta | |
| | | | |
| | | o The per filesystem object attributes are: | |
| | | | |
| | | type, change, size, named_attr, fsid, rdattr_error, filehandle, | |
| | | ACL, archive, fileid, hidden, maxlink, mimetype, mode, numlinks, | |
| | | owner, owner_group, rawdev, space_used, system, time_access, | |
| | | time_backup, time_create, time_metadata, time_modify, | |
| | | mounted_on_fileid | |
| | | | |
| | | For quota_avail_hard, quota_avail_soft, and quota_used see their | |
| | | definitions below for the appropriate classification. | |
| | | | |
| | | 5.5. Mandatory Attributes - Definitions | |
| | | | |
| | | +-----------------+----+------------+--------+----------------------+ | |
| | | | Name | Id | Data Type | Access | Description | | |
| | | +-----------------+----+------------+--------+----------------------+ | |
| | | | supp_attr | 0 | bitmap | READ | The bit vector which | | |
| | | | | | | | would retrieve all | | |
| | | | | | | | mandatory and | | |
| | | | | | | | recommended | | |
| | | | | | | | attributes that are | | |
| | | | | | | | supported for this | | |
| | | | | | | | object. The scope of | | |
| | | | | | | | this attribute | | |
| | | | | | | | applies to all | | |
| | | | | | | | objects with a | | |
| | | | | | | | matching fsid. | | |
| | | | type | 1 | nfs4_ftype | READ | The type of the | | |
| | | | | | | | object (file, | | |
| | | | | | | | directory, symlink, | | |
| | | | | | | | etc.) | | |
| | | | fh_expire_type | 2 | uint32 | READ | Server uses this to | | |
| | | | | | | | specify filehandle | | |
| | | | | | | | expiration behavior | | |
| | | | | | | | to the client. See | | |
| | | | | | | | Section 4 | | |
| | | | | | | | "Filehandles" for | | |
| | | | | | | | additional | | |
| | | | | | | | description. | | |
| | | | change | 3 | uint64 | READ | A value created by | | |
| | | | | | | | the server that the | | |
| | | | | | | | client can use to | | |
| | | | | | | | determine if file | | |
| | | | | | | | data, directory | | |
| | | | | | | | contents or | | |
| | | | | | | | attributes of the | | |
| | | | | | | | object have been | | |
| | | | | | | | modified. The server | | |
| | | | | | | | may return the | | |
| | | | | | | | object's | | |
| | | | | | | | time_metadata | | |
| | | | | | | | attribute for this | | |
| | | | | | | | attribute's value | | |
| | | | | | | | but only if the | | |
| | | | | | | | filesystem object | | |
| | | | | | | | can not be updated | | |
| | | | | | | | more frequently than | | |
| | | | | | | | the resolution of | | |
| | | | | | | | time_metadata. | | |
| | | | size | 4 | uint64 | R/W | The size of the | | |
| | | | | | | | object in bytes. | | |
| | | | link_support | 5 | bool | READ | True, if the | | |
| | | | | | | | object's filesystem | | |
| | | | | | | | supports hard links. | | |
| | | | symlink_support | 6 | bool | READ | True, if the | | |
| | | | | | | | object's filesystem | | |
| | | | | | | | supports symbolic | | |
| | | | | | | | links. | | |
| | | | named_attr | 7 | bool | READ | True, if this object | | |
| | | | | | | | has named | | |
| | | | | | | | attributes. In other | | |
| | | | | | | | words, object has a | | |
| | | | | | | | non-empty named | | |
| | | | | | | | attribute directory. | | |
| | | | fsid | 8 | fsid4 | READ | Unique filesystem | | |
| | | | | | | | identifier for the | | |
| | | | | | | | filesystem holding | | |
| | | | | | | | this object. fsid | | |
| | | | | | | | contains major and | | |
| | | | | | | | minor components | | |
| | | | | | | | each of which are | | |
| | | | | | | | uint64. | | |
| | | | unique_handles | 9 | bool | READ | True, if two | | |
| | | | | | | | distinct filehandles | | |
| | | | | | | | guaranteed to refer | | |
| | | | | | | | to two different | | |
| | | | | | | | filesystem objects. | | |
| | | | lease_time | 10 | nfs_lease4 | READ | Duration of leases | | |
| | | | | | | | at server in | | |
| | | | | | | | seconds. | | |
| | | | rdattr_error | 11 | enum | READ | Error returned from | | |
| | | | | | | | getattr during | | |
| | | | | | | | readdir. | | |
| | | | filehandle | 19 | nfs_fh4 | READ | The filehandle of | | |
| | | | | | | | this object | | |
| | | | | | | | (primarily for | | |
| | | | | | | | readdir requests). | | |
| | | +-----------------+----+------------+--------+----------------------+ | |
| | | | |
| | | Table 2 | |
| | | | |
| | | 5.6. Recommended Attributes - Definitions | |
| | | | |
| | | +-------------------+----+--------------+--------+------------------+ | |
| | | | Name | Id | Data Type | Access | Description | | |
| | | +-------------------+----+--------------+--------+------------------+ | |
| | | | ACL | 12 | nfsace4<> | R/W | The access | | |
| | | | | | | | control list for | | |
| | | | | | | | the object. | | |
| | | | aclsupport | 13 | uint32 | READ | Indicates what | | |
| | | | | | | | types of ACLs | | |
| | | | | | | | are supported on | | |
| | | | | | | | the current | | |
| | | | | | | | filesystem. | | |
| | | | archive | 14 | bool | R/W | True, if this | | |
| | | | | | | | file has been | | |
| | | | | | | | archived since | | |
| | | | | | | | the time of last | | |
| | | | | | | | modification | | |
| | | | | | | | (deprecated in | | |
| | | | | | | | favor of | | |
| | | | | | | | time_backup). | | |
| | | | cansettime | 15 | bool | READ | True, if the | | |
| | | | | | | | server is able | | |
| | | | | | | | to change the | | |
| | | | | | | | times for a | | |
| | | | | | | | filesystem | | |
| | | | | | | | object as | | |
| | | | | | | | specified in a | | |
| | | | | | | | SETATTR | | |
| | | | | | | | operation. | | |
| | | | case_insensitive | 16 | bool | READ | True, if | | |
| | | | | | | | filename | | |
| | | | | | | | comparisons on | | |
| | | | | | | | this filesystem | | |
| | | | | | | | are case | | |
| | | | | | | | insensitive. | | |
| | | | case_preserving | 17 | bool | READ | True, if | | |
| | | | | | | | filename case on | | |
| | | | | | | | this filesystem | | |
| | | | | | | | are preserved. | | |
| | | | chown_restricted | 18 | bool | READ | If TRUE, the | | |
| | | | | | | | server will | | |
| | | | | | | | reject any | | |
| | | | | | | | request to | | |
| | | | | | | | change either | | |
| | | | | | | | the owner or the | | |
| | | | | | | | group associated | | |
| | | | | | | | with a file if | | |
| | | | | | | | the caller is | | |
| | | | | | | | not a privileged | | |
| | | | | | | | user (for | | |
| | | | | | | | example, "root" | | |
| | | | | | | | in UNIX | | |
| | | | | | | | operating | | |
| | | | | | | | environments or | | |
| | | | | | | | in Windows 2000 | | |
| | | | | | | | the "Take | | |
| | | | | | | | Ownership" | | |
| | | | | | | | privilege). | | |
| | | | fileid | 20 | uint64 | READ | A number | | |
| | | | | | | | uniquely | | |
| | | | | | | | identifying the | | |
| | | | | | | | file within the | | |
| | | | | | | | filesystem. | | |
| | | | files_avail | 21 | uint64 | READ | File slots | | |
| | | | | | | | available to | | |
| | | | | | | | this user on the | | |
| | | | | | | | filesystem | | |
| | | | | | | | containing this | | |
| | | | | | | | object - this | | |
| | | | | | | | should be the | | |
| | | | | | | | smallest | | |
| | | | | | | | relevant limit. | | |
| | | | files_free | 22 | uint64 | READ | Free file slots | | |
| | | | | | | | on the | | |
| | | | | | | | filesystem | | |
| | | | | | | | containing this | | |
| | | | | | | | object - this | | |
| | | | | | | | should be the | | |
| | | | | | | | smallest | | |
| | | | | | | | relevant limit. | | |
| | | | files_total | 23 | uint64 | READ | Total file slots | | |
| | | | | | | | on the | | |
| | | | | | | | filesystem | | |
| | | | | | | | containing this | | |
| | | | | | | | object. | | |
| | | | fs_locations | 24 | fs_locations | READ | Locations where | | |
| | | | | | | | this filesystem | | |
| | | | | | | | may be found. If | | |
| | | | | | | | the server | | |
| | | | | | | | returns | | |
| | | | | | | | NFS4ERR_MOVED as | | |
| | | | | | | | an error, this | | |
| | | | | | | | attribute MUST | | |
| | | | | | | | be supported. | | |
| | | | hidden | 25 | bool | R/W | True, if the | | |
| | | | | | | | file is | | |
| | | | | | | | considered | | |
| | | | | | | | hidden with | | |
| | | | | | | | respect to the | | |
| | | | | | | | Windows API. | | |
| | | | homogeneous | 26 | bool | READ | True, if this | | |
| | | | | | | | object's | | |
| | | | | | | | filesystem is | | |
| | | | | | | | homogeneous, | | |
| | | | | | | | i.e., are per | | |
| | | | | | | | filesystem | | |
| | | | | | | | attributes the | | |
| | | | | | | | same for all | | |
| | | | | | | | filesystem's | | |
| | | | | | | | objects? | | |
| | | | maxfilesize | 27 | uint64 | READ | Maximum | | |
| | | | | | | | supported file | | |
| | | | | | | | size for the | | |
| | | | | | | | filesystem of | | |
| | | | | | | | this object. | | |
| | | | maxlink | 28 | uint32 | READ | Maximum number | | |
| | | | | | | | of links for | | |
| | | | | | | | this object. | | |
| | | | maxname | 29 | uint32 | READ | Maximum filename | | |
| | | | | | | | size supported | | |
| | | | | | | | for this object. | | |
| | | | maxread | 30 | uint64 | READ | Maximum read | | |
| | | | | | | | size supported | | |
| | | | | | | | for this object. | | |
| | | | maxwrite | 31 | uint64 | READ | Maximum write | | |
| | | | | | | | size supported | | |
| | | | | | | | for this object. | | |
| | | | | | | | This attribute | | |
| | | | | | | | SHOULD be | | |
| | | | | | | | supported if the | | |
| | | | | | | | file is | | |
| | | | | | | | writable. Lack | | |
| | | | | | | | of this | | |
| | | | | | | | attribute can | | |
| | | | | | | | lead to the | | |
| | | | | | | | client either | | |
| | | | | | | | wasting | | |
| | | | | | | | bandwidth or not | | |
| | | | | | | | receiving the | | |
| | | | | | | | best | | |
| | | | | | | | performance. | | |
| | | | mimetype | 32 | utf8<> | R/W | MIME body | | |
| | | | | | | | type/subtype of | | |
| | | | | | | | this object. | | |
| | | | mode | 33 | mode4 | R/W | UNIX-style mode | | |
| | | | | | | | and permission | | |
| | | | | | | | bits for this | | |
| | | | | | | | object. | | |
| | | | no_trunc | 34 | bool | READ | True, if a name | | |
| | | | | | | | longer than | | |
| | | | | | | | name_max is | | |
| | | | | | | | used, an error | | |
| | | | | | | | be returned and | | |
| | | | | | | | name is not | | |
| | | | | | | | truncated. | | |
| | | | numlinks | 35 | uint32 | READ | Number of hard | | |
| | | | | | | | links to this | | |
| | | | | | | | object. | | |
| | | | owner | 36 | utf8<> | R/W | The string name | | |
| | | | | | | | of the owner of | | |
| | | | | | | | this object. | | |
| | | | owner_group | 37 | utf8<> | R/W | The string name | | |
| | | | | | | | of the group | | |
| | | | | | | | ownership of | | |
| | | | | | | | this object. | | |
| | | | quota_avail_hard | 38 | uint64 | READ | For definition | | |
| | | | | | | | see Section 5.10 | | |
| | | | | | | | "Quota | | |
| | | | | | | | Attributes" | | |
| | | | | | | | below. | | |
| | | | quota_avail_soft | 39 | uint64 | READ | For definition | | |
| | | | | | | | see Section 5.10 | | |
| | | | | | | | "Quota | | |
| | | | | | | | Attributes" | | |
| | | | | | | | below. | | |
| | | | quota_used | 40 | uint64 | READ | For definition | | |
| | | | | | | | see Section 5.10 | | |
| | | | | | | | "Quota | | |
| | | | | | | | Attributes" | | |
| | | | | | | | below. | | |
| | | | rawdev | 41 | specdata4 | READ | Raw device | | |
| | | | | | | | identifier. UNIX | | |
| | | | | | | | device | | |
| | | | | | | | major/minor node | | |
| | | | | | | | information. If | | |
| | | | | | | | the value of | | |
| | | | | | | | type is not | | |
| | | | | | | | NF4BLK or | | |
| | | | | | | | NF4CHR, the | | |
| | | | | | | | value return | | |
| | | | | | | | SHOULD NOT be | | |
| | | | | | | | considered | | |
| | | | | | | | useful. | | |
| | | | space_avail | 42 | uint64 | READ | Disk space in | | |
| | | | | | | | bytes available | | |
| | | | | | | | to this user on | | |
| | | | | | | | the filesystem | | |
| | | | | | | | containing this | | |
| | | | | | | | object - this | | |
| | | | | | | | should be the | | |
| | | | | | | | smallest | | |
| | | | | | | | relevant limit. | | |
| | | | space_free | 43 | uint64 | READ | Free disk space | | |
| | | | | | | | in bytes on the | | |
| | | | | | | | filesystem | | |
| | | | | | | | containing this | | |
| | | | | | | | object - this | | |
| | | | | | | | should be the | | |
| | | | | | | | smallest | | |
| | | | | | | | relevant limit. | | |
| | | | space_total | 44 | uint64 | READ | Total disk space | | |
| | | | | | | | in bytes on the | | |
| | | | | | | | filesystem | | |
| | | | | | | | containing this | | |
| | | | | | | | object. | | |
| | | | space_used | 45 | uint64 | READ | Number of | | |
| | | | | | | | filesystem bytes | | |
| | | | | | | | allocated to | | |
| | | | | | | | this object. | | |
| | | | system | 46 | bool | R/W | True, if this | | |
| | | | | | | | file is a | | |
| | | | | | | | "system" file | | |
| | | | | | | | with respect to | | |
| | | | | | | | the Windows API. | | |
| | | | time_access | 47 | nfstime4 | READ | The time of last | | |
| | | | | | | | access to the | | |
| | | | | | | | object by a read | | |
| | | | | | | | that was | | |
| | | | | | | | satisfied by the | | |
| | | | | | | | server. | | |
| | | | time_access_set | 48 | settime4 | WRITE | Set the time of | | |
| | | | | | | | last access to | | |
| | | | | | | | the object. | | |
| | | | | | | | SETATTR use | | |
| | | | | | | | only. | | |
| | | | time_backup | 49 | nfstime4 | R/W | The time of last | | |
| | | | | | | | backup of the | | |
| | | | | | | | object. | | |
| | | | time_create | 50 | nfstime4 | R/W | The time of | | |
| | | | | | | | creation of the | | |
| | | | | | | | object. This | | |
| | | | | | | | attribute does | | |
| | | | | | | | not have any | | |
| | | | | | | | relation to the | | |
| | | | | | | | traditional UNIX | | |
| | | | | | | | file attribute | | |
| | | | | | | | "ctime" or | | |
| | | | | | | | "change time". | | |
| | | | time_delta | 51 | nfstime4 | READ | Smallest useful | | |
| | | | | | | | server time | | |
| | | | | | | | granularity. | | |
| | | | time_metadata | 52 | nfstime4 | READ | The time of last | | |
| | | | | | | | meta-data | | |
| | | | | | | | modification of | | |
| | | | | | | | the object. | | |
| | | | time_modify | 53 | nfstime4 | READ | The time of last | | |
| | | | | | | | modification to | | |
| | | | | | | | the object. | | |
| | | | time_modify_set | 54 | settime4 | WRITE | Set the time of | | |
| | | | | | | | last | | |
| | | | | | | | modification to | | |
| | | | | | | | the object. | | |
| | | | | | | | SETATTR use | | |
| | | | | | | | only. | | |
| | | | mounted_on_fileid | 55 | uint64 | READ | Like fileid, but | | |
| | | | | | | | if the target | | |
| | | | | | | | filehandle is | | |
| | | | | | | | the root of a | | |
| | | | | | | | filesystem | | |
| | | | | | | | return the | | |
| | | | | | | | fileid of the | | |
| | | | | | | | underlying | | |
| | | | | | | | directory. | | |
| | | +-------------------+----+--------------+--------+------------------+ | |
| | | | |
| | | Table 3 | |
| | | | |
| | | 5.7. Time Access | |
| | | | |
| | | As defined above, the time_access attribute represents the time of | |
| | | last access to the object by a read that was satisfied by the server. | |
| | | The notion of what is an "access" depends on server's operating | |
| | | environment and/or the server's filesystem semantics. For example, | |
| | | for servers obeying POSIX semantics, time_access would be updated | |
| | | only by the READLINK, READ, and READDIR operations and not any of the | |
| | | operations that modify the content of the object. Of course, setting | |
| | | the corresponding time_access_set attribute is another way to modify | |
| | | the time_access attribute. | |
| | | | |
| | | Whenever the file object resides on a writable filesystem, the server | |
| | | should make best efforts to record time_access into stable storage. | |
| | | However, to mitigate the performance effects of doing so, and most | |
| | | especially whenever the server is satisfying the read of the object's | |
| | | content from its cache, the server MAY cache access time updates and | |
| | | lazily write them to stable storage. It is also acceptable to give | |
| | | administrators of the server the option to disable time_access | |
| | | updates. | |
| | | | |
| | | 5.8. Interpreting owner and owner_group | |
| | | | |
| | | The recommended attributes "owner" and "owner_group" (and also users | |
| | | and groups within the "acl" attribute) are represented in terms of a | |
| | | UTF-8 string. To avoid a representation that is tied to a particular | |
| | | underlying implementation at the client or server, the use of the | |
| | | UTF-8 string has been chosen. Note that section 6.1 of [24] provides | |
| | | additional rationale. It is expected that the client and server will | |
| | | have their own local representation of owner and owner_group that is | |
| | | used for local storage or presentation to the end user. Therefore, | |
| | | it is expected that when these attributes are transferred between the | |
| | | client and server that the local representation is translated to a | |
| | | syntax of the form "user@dns_domain". This will allow for a client | |
| | | and server that do not use the same local representation the ability | |
| | | to translate to a common syntax that can be interpreted by both. | |
| | | | |
| | | Similarly, security principals may be represented in different ways | |
| | | by different security mechanisms. Servers normally translate these | |
| | | representations into a common format, generally that used by local | |
| | | storage, to serve as a means of identifying the users corresponding | |
| | | to these security principals. When these local identifiers are | |
| | | translated to the form of the owner attribute, associated with files | |
| | | created by such principals they identify, in a common format, the | |
| | | users associated with each corresponding set of security principals. | |
| | | | |
| | | The translation used to interpret owner and group strings is not | |
| | | specified as part of the protocol. This allows various solutions to | |
| | | be employed. For example, a local translation table may be consulted | |
| | | that maps between a numeric id to the user@dns_domain syntax. A name | |
| | | service may also be used to accomplish the translation. A server may | |
| | | provide a more general service, not limited by any particular | |
| | | translation (which would only translate a limited set of possible | |
| | | strings) by storing the owner and owner_group attributes in local | |
| | | storage without any translation or it may augment a translation | |
| | | method by storing the entire string for attributes for which no | |
| | | translation is available while using the local representation for | |
| | | those cases in which a translation is available. | |
| | | | |
| | | Servers that do not provide support for all possible values of the | |
| | | owner and owner_group attributes, should return an error | |
| | | (NFS4ERR_BADOWNER) when a string is presented that has no | |
| | | translation, as the value to be set for a SETATTR of the owner, | |
| | | owner_group, or acl attributes. When a server does accept an owner | |
| | | or owner_group value as valid on a SETATTR (and similarly for the | |
| | | owner and group strings in an acl), it is promising to return that | |
| | | same string when a corresponding GETATTR is done. Configuration | |
| | | changes and ill-constructed name translations (those that contain | |
| | | aliasing) may make that promise impossible to honor. Servers should | |
| | | make appropriate efforts to avoid a situation in which these | |
| | | attributes have their values changed when no real change to ownership | |
| | | has occurred. | |
| | | | |
| | | The "dns_domain" portion of the owner string is meant to be a DNS | |
| | | domain name. For example, user@ietf.org. Servers should accept as | |
| | | valid a set of users for at least one domain. A server may treat | |
| | | other domains as having no valid translations. A more general | |
| | | service is provided when a server is capable of accepting users for | |
| | | multiple domains, or for all domains, subject to security | |
| | | constraints. | |
| | | | |
| | | In the case where there is no translation available to the client or | |
| | | server, the attribute value must 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 | |
| | | a basis for translation into its own internal format. Even though | |
| | | the attribute value can not be translated, it may still be useful. | |
| | | In the case of a client, the attribute string may be used for local | |
| | | display of ownership. | |
| | | | |
| | | To provide a greater degree of compatibility with previous versions | |
| | | of NFS (i.e., v2 and v3), which identified users and groups by 32-bit | |
| | | unsigned uid's and gid's, owner and group strings that consist of | |
| | | decimal numeric values with no leading zeros can be given a special | |
| | | interpretation by clients and servers which choose to provide such | |
| | | support. The receiver may treat such a user or group string as | |
| | | representing the same user as would be represented by a v2/v3 uid or | |
| | | gid having the corresponding numeric value. A server is not | |
| | | obligated to accept such a string, but may return an NFS4ERR_BADOWNER | |
| | | instead. To avoid this mechanism being used to subvert user and | |
| | | group translation, so that a client might pass all of the owners and | |
| | | groups in numeric form, a server SHOULD return an NFS4ERR_BADOWNER | |
| | | error when there is a valid translation for the user or owner | |
| | | designated in this way. In that case, the client must use the | |
| | | appropriate name@domain string and not the special form for | |
| | | compatibility. | |
| | | | |
| | | The owner string "nobody" may be used to designate an anonymous user, | |
| | | which will be associated with a file created by a security principal | |
| | | that cannot be mapped through normal means to the owner attribute. | |
| | | | |
| | | 5.9. Character Case Attributes | |
| | | | |
| | | With respect to the case_insensitive and case_preserving attributes, | |
| | | each UCS-4 character (which UTF-8 encodes) has a "long descriptive | |
| | | name" [25] which may or may not included the word "CAPITAL" or | |
| | | "SMALL". The presence of SMALL or CAPITAL allows an NFS server to | |
| | | implement unambiguous and efficient table driven mappings for case | |
| | | insensitive comparisons, and non-case-preserving storage. For | |
| | | general character handling and internationalization issues, see | |
| | | Section 1 "Internationalization". | |
| | | | |
| | | 5.10. Quota Attributes | |
| | | | |
| | | For the attributes related to filesystem quotas, the following | |
| | | definitions apply: | |
| | | | |
| | | quota_avail_soft The value in bytes which represents the amount of | |
| | | additional disk space that can be allocated to this file or | |
| | | directory before the user may reasonably be warned. It is | |
| | | understood that this space may be consumed by allocations to other | |
| | | files or directories though there is a rule as to which other | |
| | | files or directories. | |
| | | | |
| | | quota_avail_hard The value in bytes which represent the amount of | |
| | | additional disk space beyond the current allocation that can be | |
| | | allocated to this file or directory before further allocations | |
| | | will be refused. It is understood that this space may be consumed | |
| | | by allocations to other files or directories. | |
| | | | |
| | | quota_used The value in bytes which represent the amount of disc | |
| | | space used by this file or directory and possibly a number of | |
| | | other similar files or directories, where the set of "similar" | |
| | | meets at least the criterion that allocating space to any file or | |
| | | directory in the set will reduce the "quota_avail_hard" of every | |
| | | other file or directory in the set. | |
| | | | |
| | | Note that there may be a number of distinct but overlapping sets | |
| | | of files or directories for which a quota_used value is maintained | |
| | | (e.g., "all files with a given owner", "all files with a given | |
| | | group owner", etc.). | |
| | | | |
| | | The server is at liberty to choose any of those sets but should do | |
| | | so in a repeatable way. The rule may be configured per-filesystem | |
| | | or may be "choose the set with the smallest quota". | |
| | | | |
| | | 5.11. Access Control Lists | |
| | | | |
| | | The NFS version 4 ACL attribute is an array of access control entries | |
| | | (ACE). Although, the client can read and write the ACL attribute, | |
| | | the NFSv4 model is the server does all access control based on the | |
| | | server's interpretation of the ACL. If at any point the client wants | |
| | | to check access without issuing an operation that modifies or reads | |
| | | data or metadata, the client can use the OPEN and ACCESS operations | |
| | | to do so. There are various access control entry types, as defined | |
| | | in the Section "ACE type". The server is able to communicate which | |
| | | ACE types are supported by returning the appropriate value within the | |
| | | aclsupport attribute. Each ACE covers one or more operations on a | |
| | | file or directory as described in the Section "ACE Access Mask". It | |
| | | may also contain one or more flags that modify the semantics of the | |
| | | ACE as defined in the Section "ACE flag". | |
| | | | |
| | | The NFS ACE attribute is defined as follows: | |
| | | | |
| | | typedef uint32_t acetype4; | |
| | | | |
| | | typedef uint32_t aceflag4; | |
| | | | |
| | | typedef uint32_t acemask4; | |
| | | | |
| | | struct nfsace4 { | |
| | | acetype4 type; | |
| | | aceflag4 flag; | |
| | | acemask4 access_mask; | |
| | | utf8str_mixed who; | |
| | | }; | |
| | | | |
| | | To determine if a request succeeds, each nfsace4 entry is processed | |
| | | in order by the server. Only ACEs which have a "who" that matches | |
| | | the requester are considered. Each ACE is processed until all of the | |
| | | bits of the requester's access have been ALLOWED. Once a bit (see | |
| | | below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it is no longer | |
| | | considered in the processing of later ACEs. If an ACCESS_DENIED_ACE | |
| | | is encountered where the requester's access still has unALLOWED bits | |
| | | in common with the "access_mask" of the ACE, the request is denied. | |
| | | However, unlike the ALLOWED and DENIED ACE types, the ALARM and AUDIT | |
| | | ACE types do not affect a requester's access, and instead are for | |
| | | triggering events as a result of a requester's access attempt. | |
| | | | |
| | | Therefore, all AUDIT and ALARM ACEs are processed until end of the | |
| | | ACL. When the ACL is fully processed, if there are bits in | |
| | | requester's mask that have not been considered whether the server | |
| | | allows or denies the access is undefined. If there is a mode | |
| | | attribute on the file, then this cannot happen, since the mode's | |
| | | MODE4_*OTH bits will map to EVERYONE@ ACEs that unambiguously specify | |
| | | the requester's access. | |
| | | | |
| | | The NFS version 4 ACL model is quite rich. Some server platforms may | |
| | | provide access control functionality that goes beyond the UNIX-style | |
| | | mode attribute, but which is not as rich as the NFS ACL model. So | |
| | | that users can take advantage of this more limited functionality, the | |
| | | server may indicate that it supports ACLs as long as it follows the | |
| | | guidelines for mapping between its ACL model and the NFS version 4 | |
| | | ACL model. | |
| | | | |
| | | The situation is complicated by the fact that a server may have | |
| | | multiple modules that enforce ACLs. For example, the enforcement for | |
| | | NFS version 4 access may be different from the enforcement for local | |
| | | access, and both may be different from the enforcement for access | |
| | | through other protocols such as SMB. So it may be useful for a | |
| | | server to accept an ACL even if not all of its modules are able to | |
| | | support it. | |
| | | | |
| | | The guiding principle in all cases is that the server must not accept | |
| | | ACLs that appear to make the file more secure than it really is. | |
| | | | |
| | | 5.11.1. ACE type | |
| | | | |
| | | +-------+-----------------------------------------------------------+ | |
| | | | Type | Description | | |
| | | +-------+-----------------------------------------------------------+ | |
| | | | ALLOW | Explicitly grants the access defined in acemask4 to the | | |
| | | | | file or directory. | | |
| | | | DENY | Explicitly denies the access defined in acemask4 to the | | |
| | | | | file or directory. | | |
| | | | AUDIT | LOG (system dependent) any access attempt to a file or | | |
| | | | | directory which uses any of the access methods specified | | |
| | | | | in acemask4. | | |
| | | | ALARM | Generate a system ALARM (system dependent) when any | | |
| | | | | access attempt is made to a file or directory for the | | |
| | | | | access methods specified in acemask4. | | |
| | | +-------+-----------------------------------------------------------+ | |
| | | | |
| | | Table 4 | |
| | | | |
| | | A server need not support all of the above ACE types. The bitmask | |
| | | constants used to represent the above definitions within the | |
| | | aclsupport attribute are as follows: | |
| | | | |
| | | const ACL4_SUPPORT_ALLOW_ACL = 0x00000001; | |
| | | const ACL4_SUPPORT_DENY_ACL = 0x00000002; | |
| | | const ACL4_SUPPORT_AUDIT_ACL = 0x00000004; | |
| | | const ACL4_SUPPORT_ALARM_ACL = 0x00000008; | |
| | | | |
| | | The semantics of the "type" field follow the descriptions provided | |
| | | above. | |
| | | | |
| | | The constants used for the type field (acetype4) are as follows: | |
| | | | |
| | | const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000; | |
| | | const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001; | |
| | | const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002; | |
| | | const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003; | |
| | | | |
| | | Clients should not attempt to set an ACE unless the server claims | |
| | | support for that ACE type. If the server receives a request to set | |
| | | an ACE that it cannot store, it MUST reject the request with | |
| | | NFS4ERR_ATTRNOTSUPP. If the server receives a request to set an ACE | |
| | | that it can store but cannot enforce, the server SHOULD reject the | |
| | | request with NFS4ERR_ATTRNOTSUPP. | |
| | | | |
| | | Example: suppose a server can enforce NFS ACLs for NFS access but | |
| | | cannot enforce ACLs for local access. If arbitrary processes can run | |
| | | on the server, then the server SHOULD NOT indicate ACL support. On | |
| | | the other hand, if only trusted administrative programs run locally, | |
| | | then the server may indicate ACL support. | |
| | | | |
| | | 5.11.2. ACE Access Mask | |
| | | | |
| | | The access_mask field contains values based on the following: | |
| | | | |
| | | +-------------------+-----------------------------------------------+ | |
| | | | Access | Description | | |
| | | +-------------------+-----------------------------------------------+ | |
| | | | READ_DATA | Permission to read the data of the file | | |
| | | | LIST_DIRECTORY | Permission to list the contents of a | | |
| | | | | directory | | |
| | | | WRITE_DATA | Permission to modify the file's data | | |
| | | | ADD_FILE | Permission to add a new file to a directory | | |
| | | | APPEND_DATA | Permission to append data to a file | | |
| | | | ADD_SUBDIRECTORY | Permission to create a subdirectory to a | | |
| | | | | directory | | |
| | | | READ_NAMED_ATTRS | Permission to read the named attributes of a | | |
| | | | | file | | |
| | | | WRITE_NAMED_ATTRS | Permission to write the named attributes of a | | |
| | | | | file | | |
| | | | EXECUTE | Permission to execute a file | | |
| | | | DELETE_CHILD | Permission to delete a file or directory | | |
| | | | | within a directory | | |
| | | | READ_ATTRIBUTES | The ability to read basic attributes | | |
| | | | | (non-acls) of a file | | |
| | | | WRITE_ATTRIBUTES | Permission to change basic attributes | | |
| | | | | (non-acls) of a file | | |
| | | | DELETE | Permission to Delete the file | | |
| | | | READ_ACL | Permission to Read the ACL | | |
| | | | WRITE_ACL | Permission to Write the ACL | | |
| | | | WRITE_OWNER | Permission to change the owner | | |
| | | | SYNCHRONIZE | Permission to access file locally at the | | |
| | | | | server with synchronous reads and writes | | |
| | | +-------------------+-----------------------------------------------+ | |
| | | | |
| | | Table 5 | |
| | | | |
| | | The bitmask constants used for the access mask field are as follows: | |
| | | | |
| | | const ACE4_READ_DATA = 0x00000001; | |
| | | const ACE4_LIST_DIRECTORY = 0x00000001; | |
| | | const ACE4_WRITE_DATA = 0x00000002; | |
| | | const ACE4_ADD_FILE = 0x00000002; | |
| | | const ACE4_APPEND_DATA = 0x00000004; | |
| | | const ACE4_ADD_SUBDIRECTORY = 0x00000004; | |
| | | const ACE4_READ_NAMED_ATTRS = 0x00000008; | |
| | | const ACE4_WRITE_NAMED_ATTRS = 0x00000010; | |
| | | const ACE4_EXECUTE = 0x00000020; | |
| | | const ACE4_DELETE_CHILD = 0x00000040; | |
| | | const ACE4_READ_ATTRIBUTES = 0x00000080; | |
| | | const ACE4_WRITE_ATTRIBUTES = 0x00000100; | |
| | | | |
| | | const ACE4_DELETE = 0x00010000; | |
| | | const ACE4_READ_ACL = 0x00020000; | |
| | | const ACE4_WRITE_ACL = 0x00040000; | |
| | | const ACE4_WRITE_OWNER = 0x00080000; | |
| | | const ACE4_SYNCHRONIZE = 0x00100000; | |
| | | | |
| | | Server implementations need not provide the granularity of control | |
| | | that is implied by this list of masks. For example, POSIX-based | |
| | | systems might not distinguish APPEND_DATA (the ability to append to a | |
| | | file) from WRITE_DATA (the ability to modify existing contents); both | |
| | | masks would be tied to a single "write" permission. When such a | |
| | | server returns attributes to the client, it would show both | |
| | | APPEND_DATA and WRITE_DATA if and only if the write permission is | |
| | | enabled. | |
| | | | |
| | | If a server receives a SETATTR request that it cannot accurately | |
| | | implement, it should error in the direction of more restricted | |
| | | access. For example, suppose a server cannot distinguish overwriting | |
| | | data from appending new data, as described in the previous paragraph. | |
| | | If a client submits an ACE where APPEND_DATA is set but WRITE_DATA is | |
| | | not (or vice versa), the server should reject the request with | |
| | | NFS4ERR_ATTRNOTSUPP. Nonetheless, if the ACE has type DENY, the | |
| | | server may silently turn on the other bit, so that both APPEND_DATA | |
| | | and WRITE_DATA are denied. | |
| | | | |
| | | 5.11.3. ACE flag | |
| | | | |
| | | The "flag" field contains values based on the following descriptions. | |
| | | | |
| | | ACE4_FILE_INHERIT_ACE Can be placed on a directory and indicates | |
| | | that this ACE should be added to each new non-directory file | |
| | | created. | |
| | | | |
| | | ACE4_DIRECTORY_INHERIT_ACE Can be placed on a directory and | |
| | | indicates that this ACE should be added to each new directory | |
| | | created. | |
| | | | |
| | | ACE4_INHERIT_ONLY_ACE Can be placed on a directory but does not | |
| | | apply to the directory, only to newly created files/directories as | |
| | | specified by the above two flags. | |
| | | | |
| | | ACE4_NO_PROPAGATE_INHERIT_ACE Can be placed on a directory. | |
| | | Normally when a new directory is created and an ACE exists on the | |
| | | parent directory which is marked ACL4_DIRECTORY_INHERIT_ACE, two | |
| | | ACEs are placed on the new directory. One for the directory | |
| | | itself and one which is an inheritable ACE for newly created | |
| | | directories. This flag tells the server to not place an ACE on | |
| | | the newly created directory which is inheritable by subdirectories | |
| | | of the created directory. | |
| | | | |
| | | ACE4_SUCCESSFUL_ACCESS_ACE_FLAG | |
| | | | |
| | | ACL4_FAILED_ACCESS_ACE_FLAG The ACE4_SUCCESSFUL_ACCESS_ACE_FLAG | |
| | | (SUCCESS) and ACE4_FAILED_ACCESS_ACE_FLAG (FAILED) flag bits | |
| | | relate only to ACE4_SYSTEM_AUDIT_ACE_TYPE (AUDIT) and | |
| | | ACE4_SYSTEM_ALARM_ACE_TYPE (ALARM) ACE types. If during the | |
| | | processing of the file's ACL, the server encounters an AUDIT or | |
| | | ALARM ACE that matches the principal attempting the OPEN, the | |
| | | server notes that fact, and the presence, if any, of the SUCCESS | |
| | | and FAILED flags encountered in the AUDIT or ALARM ACE. Once the | |
| | | server completes the ACL processing, and the share reservation | |
| | | processing, and the OPEN call, it then notes if the OPEN succeeded | |
| | | or failed. If the OPEN succeeded, and if the SUCCESS flag was set | |
| | | for a matching AUDIT or ALARM, then the appropriate AUDIT or ALARM | |
| | | event occurs. If the OPEN failed, and if the FAILED flag was set | |
| | | for the matching AUDIT or ALARM, then the appropriate AUDIT or | |
| | | ALARM event occurs. Clearly either or both of the SUCCESS or | |
| | | FAILED can be set, but if neither is set, the AUDIT or ALARM ACE | |
| | | is not useful. | |
| | | | |
| | | The previously described processing applies to that of the ACCESS | |
| | | operation as well. The difference being that "success" or | |
| | | "failure" does not mean whether ACCESS returns NFS4_OK or not. | |
| | | Success means whether ACCESS returns all requested and supported | |
| | | bits. Failure means whether ACCESS failed to return a bit that | |
| | | was requested and supported. | |
| | | | |
| | | ACE4_IDENTIFIER_GROUP Indicates that the "who" refers to a GROUP as | |
| | | defined under UNIX. | |
| | | | |
| | | The bitmask constants used for the flag field are as follows: | |
| | | | |
| | | const ACE4_FILE_INHERIT_ACE = 0x00000001; | |
| | | const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; | |
| | | const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; | |
| | | const ACE4_INHERIT_ONLY_ACE = 0x00000008; | |
| | | const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; | |
| | | const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; | |
| | | const ACE4_IDENTIFIER_GROUP = 0x00000040; | |
| | | | |
| | | A server need not support any of these flags. If the server supports | |
| | | flags that are similar to, but not exactly the same as, these flags, | |
| | | the implementation may define a mapping between the protocol-defined | |
| | | flags and the implementation-defined flags. Again, the guiding | |
| | | principle is that the file not appear to be more secure than it | |
| | | really is. | |
| | | | |
| | | For example, suppose a client tries to set an ACE with | |
| | | ACE4_FILE_INHERIT_ACE set but not ACE4_DIRECTORY_INHERIT_ACE. If the | |
| | | server does not support any form of ACL inheritance, the server | |
| | | should reject the request with NFS4ERR_ATTRNOTSUPP. If the server | |
| | | supports a single "inherit ACE" flag that applies to both files and | |
| | | directories, the server may reject the request (i.e., requiring the | |
| | | client to set both the file and directory inheritance flags). The | |
| | | server may also accept the request and silently turn on the | |
| | | ACE4_DIRECTORY_INHERIT_ACE flag. | |
| | | | |
| | | 5.11.4. ACE who | |
| | | | |
| | | There are several special identifiers ("who") which need to be | |
| | | understood universally, rather than in the context of a particular | |
| | | DNS domain. Some of these identifiers cannot be understood when an | |
| | | NFS client accesses the server, but have meaning when a local process | |
| | | accesses the file. The ability to display and modify these | |
| | | permissions is permitted over NFS, even if none of the access methods | |
| | | on the server understands the identifiers. | |
| | | | |
| | | +-----------------+------------------------------------------------+ | |
| | | | Who | Description | | |
| | | +-----------------+------------------------------------------------+ | |
| | | | "OWNER" | The owner of the file. | | |
| | | | "GROUP" | The group associated with the file. | | |
| | | | "EVERYONE" | The world. | | |
| | | | "INTERACTIVE" | Accessed from an interactive terminal. | | |
| | | | "NETWORK" | Accessed via the network. | | |
| | | | "DIALUP" | Accessed as a dialup user to the server. | | |
| | | | "BATCH" | Accessed from a batch job. | | |
| | | | "ANONYMOUS" | Accessed without any authentication. | | |
| | | | "AUTHENTICATED" | Any authenticated user (opposite of ANONYMOUS) | | |
| | | | "SERVICE" | Access from a system service. | | |
| | | +-----------------+------------------------------------------------+ | |
| | | | |
| | | Table 6 | |
| | | | |
| | | To avoid conflict, these special identifiers are distinguish by an | |
| | | appended "@" and should appear in the form "xxxx@" (note: no domain | |
| | | name after the "@"). For example: ANONYMOUS@. | |
| | | | |
| | | 5.11.5. Mode Attribute | |
| | | | |
| | | The NFS version 4 mode attribute is based on the UNIX mode bits. The | |
| | | following bits are defined: | |
| | | | |
| | | const MODE4_SUID = 0x800; /* set user id on execution */ | |
| | | const MODE4_SGID = 0x400; /* set group id on execution */ | |
| | | const MODE4_SVTX = 0x200; /* save text even after use */ | |
| | | const MODE4_RUSR = 0x100; /* read permission: owner */ | |
| | | const MODE4_WUSR = 0x080; /* write permission: owner */ | |
| | | const MODE4_XUSR = 0x040; /* execute permission: owner */ | |
| | | const MODE4_RGRP = 0x020; /* read permission: group */ | |
| | | const MODE4_WGRP = 0x010; /* write permission: group */ | |
| | | const MODE4_XGRP = 0x008; /* execute permission: group */ | |
| | | const MODE4_ROTH = 0x004; /* read permission: other */ | |
| | | const MODE4_WOTH = 0x002; /* write permission: other */ | |
| | | const MODE4_XOTH = 0x001; /* execute permission: other */ | |
| | | | |
| | | Bits MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR apply to the principal | |
| | | identified in the owner attribute. Bits MODE4_RGRP, MODE4_WGRP, and | |
| | | MODE4_XGRP apply to the principals identified in the owner_group | |
| | | attribute. Bits MODE4_ROTH, MODE4_WOTH, MODE4_XOTH apply to any | |
| | | principal that does not match that in the owner group, and does not | |
| | | have a group matching that of the owner_group attribute. | |
| | | | |
| | | The remaining bits are not defined by this protocol and MUST NOT be | |
| | | used. The minor version mechanism must be used to define further bit | |
| | | usage. | |
| | | | |
| | | Note that in UNIX, if a file has the MODE4_SGID bit set and no | |
| | | MODE4_XGRP bit set, then READ and WRITE must use mandatory file | |
| | | locking. | |
| | | | |
| | | 5.11.6. Mode and ACL Attribute | |
| | | | |
| | | The server that supports both mode and ACL must take care to | |
| | | synchronize the MODE4_*USR, MODE4_*GRP, and MODE4_*OTH bits with the | |
| | | ACEs which have respective who fields of "OWNER@", "GROUP@", and | |
| | | "EVERYONE@" so that the client can see semantically equivalent access | |
| | | permissions exist whether the client asks for owner, owner_group and | |
| | | mode attributes, or for just the ACL. | |
| | | | |
| | | Because the mode attribute includes bits (e.g., MODE4_SVTX) that have | |
| | | nothing to do with ACL semantics, it is permitted for clients to | |
| | | specify both the ACL attribute and mode in the same SETATTR | |
| | | operation. However, because there is no prescribed order for | |
| | | processing the attributes in a SETATTR, the client must ensure that | |
| | | ACL attribute, if specified without mode, would produce the desired | |
| | | mode bits, and conversely, the mode attribute if specified without | |
| | | ACL, would produce the desired "OWNER@", "GROUP@", and "EVERYONE@" | |
| | | ACEs. | |
| | | | |
| | | 5.11.7. mounted_on_fileid | |
| | | | |
| | | UNIX-based operating environments connect a filesystem into the | |
| | | namespace by connecting (mounting) the filesystem onto the existing | |
| | | file object (the mount point, usually a directory) of an existing | |
| | | filesystem. When the mount point's parent directory is read via an | |
| | | API like readdir(), the return results are directory entries, each | |
| | | with a component name and a fileid. The fileid of the mount point's | |
| | | directory entry will be different from the fileid that the stat() | |
| | | system call returns. The stat() system call is returning the fileid | |
| | | of the root of the mounted filesystem, whereas readdir() is returning | |
| | | the fileid stat() would have returned before any filesystems were | |
| | | mounted on the mount point. | |
| | | | |
| | | Unlike NFS version 3, NFS version 4 allows a client's LOOKUP request | |
| | | to cross other filesystems. The client detects the filesystem | |
| | | crossing whenever the filehandle argument of LOOKUP has an fsid | |
| | | attribute different from that of the filehandle returned by LOOKUP. | |
| | | A UNIX-based client will consider this a "mount point crossing". | |
| | | UNIX has a legacy scheme for allowing a process to determine its | |
| | | current working directory. This relies on readdir() of a mount | |
| | | point's parent and stat() of the mount point returning fileids as | |
| | | previously described. The mounted_on_fileid attribute corresponds to | |
| | | the fileid that readdir() would have returned as described | |
| | | previously. | |
| | | | |
| | | While the NFS version 4 client could simply fabricate a fileid | |
| | | corresponding to what mounted_on_fileid provides (and if the server | |
| | | does not support mounted_on_fileid, the client has no choice), there | |
| | | is a risk that the client will generate a fileid that conflicts with | |
| | | one that is already assigned to another object in the filesystem. | |
| | | Instead, if the server can provide the mounted_on_fileid, the | |
| | | potential for client operational problems in this area is eliminated. | |
| | | | |
| | | If the server detects that there is no mounted point at the target | |
| | | file object, then the value for mounted_on_fileid that it returns is | |
| | | the same as that of the fileid attribute. | |
| | | | |
| | | The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD | |
| | | provide it if possible, and for a UNIX-based server, this is | |
| | | straightforward. Usually, mounted_on_fileid will be requested during | |
| | | a READDIR operation, in which case it is trivial (at least for UNIX- | |
| | | based servers) to return mounted_on_fileid since it is equal to the | |
| | | fileid of a directory entry returned by readdir(). If | |
| | | mounted_on_fileid is requested in a GETATTR operation, the server | |
| | | should obey an invariant that has it returning a value that is equal | |
| | | to the file object's entry in the object's parent directory, i.e., | |
| | | what readdir() would have returned. Some operating environments | |
| | | allow a series of two or more filesystems to be mounted onto a single | |
| | | mount point. In this case, for the server to obey the aforementioned | |
| | | invariant, it will need to find the base mount point, and not the | |
| | | intermediate mount points. | |
| | | | |
| | | 6. Filesystem Migration and Replication | |
| | | | |
| | | With the use of the recommended attribute "fs_locations", the NFS | |
| | | version 4 server has a method of providing filesystem migration or | |
| | | replication services. For the purposes of migration and replication, | |
| | | a filesystem will be defined as all files that share a given fsid | |
| | | (both major and minor values are the same). | |
| | | | |
| | | The fs_locations attribute provides a list of filesystem locations. | |
| | | These locations are specified by providing the server name (either | |
| | | DNS domain or IP address) and the path name representing the root of | |
| | | the filesystem. Depending on the type of service being provided, the | |
| | | list will provide a new location or a set of alternate locations for | |
| | | the filesystem. The client will use this information to redirect its | |
| | | requests to the new server. | |
| | | | |
| | | 6.1. Replication | |
| | | | |
| | | It is expected that filesystem replication will be used in the case | |
| | | of read-only data. Typically, the filesystem will be replicated on | |
| | | two or more servers. The fs_locations attribute will provide the | |
| | | list of these locations to the client. On first access of the | |
| | | filesystem, the client should obtain the value of the fs_locations | |
| | | attribute. If, in the future, the client finds the server | |
| | | unresponsive, the client may attempt to use another server specified | |
| | | by fs_locations. | |
| | | | |
| | | If applicable, the client must take the appropriate steps to recover | |
| | | valid filehandles from the new server. This is described in more | |
| | | detail in the following sections. | |
| | | | |
| | | 6.2. Migration | |
| | | | |
| | | Filesystem migration is used to move a filesystem from one server to | |
| | | another. Migration is typically used for a filesystem that is | |
| | | writable and has a single copy. The expected use of migration is for | |
| | | load balancing or general resource reallocation. The protocol does | |
| | | not specify how the filesystem will be moved between servers. This | |
| | | server-to-server transfer mechanism is left to the server | |
| | | implementor. However, the method used to communicate the migration | |
| | | event between client and server is specified here. | |
| | | | |
| | | Once the servers participating in the migration have completed the | |
| | | move of the filesystem, the error NFS4ERR_MOVED will be returned for | |
| | | subsequent requests received by the original server. The | |
| | | NFS4ERR_MOVED error is returned for all operations except PUTFH and | |
| | | GETATTR. Upon receiving the NFS4ERR_MOVED error, the client will | |
| | | obtain the value of the fs_locations attribute. The client will then | |
| | | use the contents of the attribute to redirect its requests to the | |
| | | specified server. To facilitate the use of GETATTR, operations such | |
| | | as PUTFH must also be accepted by the server for the migrated file | |
| | | system's filehandles. Note that if the server returns NFS4ERR_MOVED, | |
| | | the server MUST support the fs_locations attribute. | |
| | | | |
| | | If the client requests more attributes than just fs_locations, the | |
| | | server may return fs_locations only. This is to be expected since | |
| | | the server has migrated the filesystem and may not have a method of | |
| | | obtaining additional attribute data. | |
| | | | |
| | | The server implementor needs to be careful in developing a migration | |
| | | solution. The server must consider all of the state information | |
| | | clients may have outstanding at the server. This includes but is not | |
| | | limited to locking/share state, delegation state, and asynchronous | |
| | | file writes which are represented by WRITE and COMMIT verifiers. The | |
| | | server should strive to minimize the impact on its clients during and | |
| | | after the migration process. | |
| | | | |
| | | 6.3. Interpretation of the fs_locations Attribute | |
| | | | |
| | | The fs_location attribute is structured in the following way: | |
| | | | |
| | | struct fs_location4 { | |
| | | utf8str_cis server<>; | |
| | | pathname4 rootpath; | |
| | | }; | |
| | | | |
| | | struct fs_locations4 { | |
| | | pathname4 fs_root; | |
| | | fs_location4 locations<>; | |
| | | }; | |
| | | | |
| | | The fs_location struct is used to represent the location of a | |
| | | filesystem by providing a server name and the path to the root of the | |
| | | filesystem. For a multi-homed server or a set of servers that use | |
| | | the same rootpath, an array of server names may be provided. An | |
| | | entry in the server array is an UTF8 string and represents one of a | |
| | | traditional DNS host name, IPv4 address, or IPv6 address. It is not | |
| | | a requirement that all servers that share the same rootpath be listed | |
| | | in one fs_location struct. The array of server names is provided for | |
| | | convenience. Servers that share the same rootpath may also be listed | |
| | | in separate fs_location entries in the fs_locations attribute. | |
| | | | |
| | | The fs_locations struct and attribute then contains an array of | |
| | | locations. Since the name space of each server may be constructed | |
| | | differently, the "fs_root" field is provided. The path represented | |
| | | by fs_root represents the location of the filesystem in the server's | |
| | | name space. Therefore, the fs_root path is only associated with the | |
| | | server from which the fs_locations attribute was obtained. The | |
| | | fs_root path is meant to aid the client in locating the filesystem at | |
| | | the various servers listed. | |
| | | | |
| | | As an example, there is a replicated filesystem located at two | |
| | | servers (servA and servB). At servA the filesystem is located at | |
| | | path "/a/b/c". At servB the filesystem is located at path "/x/y/z". | |
| | | In this example the client accesses the filesystem first at servA | |
| | | with a multi-component lookup path of "/a/b/c/d". Since the client | |
| | | used a multi-component lookup to obtain the filehandle at "/a/b/c/d", | |
| | | it is unaware that the filesystem's root is located in servA's name | |
| | | space at "/a/b/c". When the client switches to servB, it will need | |
| | | to determine that the directory it first referenced at servA is now | |
| | | represented by the path "/x/y/z/d" on servB. To facilitate this, the | |
| | | fs_locations attribute provided by servA would have a fs_root value | |
| | | of "/a/b/c" and two entries in fs_location. One entry in fs_location | |
| | | will be for itself (servA) and the other will be for servB with a | |
| | | path of "/x/y/z". With this information, the client is able to | |
| | | substitute "/x/y/z" for the "/a/b/c" at the beginning of its access | |
| | | path and construct "/x/y/z/d" to use for the new server. | |
| | | | |
| | | See Section 16 "Security Considerations" for a discussion on the | |
| | | recommendations for the security flavor to be used by any GETATTR | |
| | | operation that requests the "fs_locations" attribute. | |
| | | | |
| | | 6.4. Filehandle Recovery for Migration or Replication | |
| | | | |
| | | Filehandles for filesystems that are replicated or migrated generally | |
| | | have the same semantics as for filesystems that are not replicated or | |
| | | migrated. For example, if a filesystem has persistent filehandles | |
| | | and it is migrated to another server, the filehandle values for the | |
| | | filesystem will be valid at the new server. | |
| | | | |
| | | For volatile filehandles, the servers involved likely do not have a | |
| | | mechanism to transfer filehandle format and content between | |
| | | themselves. Therefore, a server may have difficulty in determining | |
| | | if a volatile filehandle from an old server should return an error of | |
| | | NFS4ERR_FHEXPIRED. Therefore, the client is informed, with the use | |
| | | of the fh_expire_type attribute, whether volatile filehandles will | |
| | | expire at the migration or replication event. If the bit | |
| | | FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client | |
| | | must treat the volatile filehandle as if the server had returned the | |
| | | NFS4ERR_FHEXPIRED error. At the migration or replication event in | |
| | | the presence of the FH4_VOL_MIGRATION bit, the client will not | |
| | | present the original or old volatile filehandle to the new server. | |
| | | The client will start its communication with the new server by | |
| | | recovering its filehandles using the saved file names. | |
| | | | |
| | | 7. NFS Server Name Space | |
| | | | |
| | | 7.1. Server Exports | |
| | | | |
| | | On a UNIX server the name space describes all the files reachable by | |
| | | pathnames under the root directory or "/". On a Windows NT server | |
| | | the name space constitutes all the files on disks named by mapped | |
| | | disk letters. NFS server administrators rarely make the entire | |
| | | server's filesystem name space available to NFS clients. More often | |
| | | portions of the name space are made available via an "export" | |
| | | feature. In previous versions of the NFS protocol, the root | |
| | | filehandle for each export is obtained through the MOUNT protocol; | |
| | | the client sends a string that identifies the export of name space | |
| | | and the server returns the root filehandle for it. The MOUNT | |
| | | protocol supports an EXPORTS procedure that will enumerate the | |
| | | server's exports. | |
| | | | |
| | | 7.2. Browsing Exports | |
| | | | |
| | | The NFS version 4 protocol provides a root filehandle that clients | |
| | | can use to obtain filehandles for these exports via a multi-component | |
| | | LOOKUP. A common user experience is to use a graphical user | |
| | | interface (perhaps a file "Open" dialog window) to find a file via | |
| | | progressive browsing through a directory tree. The client must be | |
| | | able to move from one export to another export via single-component, | |
| | | progressive LOOKUP operations. | |
| | | | |
| | | This style of browsing is not well supported by the NFS version 2 and | |
| | | 3 protocols. The client expects all LOOKUP operations to remain | |
| | | within a single server filesystem. For example, the device attribute | |
| | | will not change. This prevents a client from taking name space paths | |
| | | that span exports. | |
| | | | |
| | | An automounter on the client can obtain a snapshot of the server's | |
| | | name space using the EXPORTS procedure of the MOUNT protocol. If it | |
| | | understands the server's pathname syntax, it can create an image of | |
| | | the server's name space on the client. The parts of the name space | |
| | | that are not exported by the server are filled in with a "pseudo | |
| | | filesystem" that allows the user to browse from one mounted | |
| | | filesystem to another. There is a drawback to this representation of | |
| | | the server's name space on the client: it is static. If the server | |
| | | administrator adds a new export the client will be unaware of it. | |
| | | | |
| | | 7.3. Server Pseudo Filesystem | |
| | | | |
| | | NFS version 4 servers avoid this name space inconsistency by | |
| | | presenting all the exports within the framework of a single server | |
| | | name space. An NFS version 4 client uses LOOKUP and READDIR | |
| | | operations to browse seamlessly from one export to another. Portions | |
| | | of the server name space that are not exported are bridged via a | |
| | | "pseudo filesystem" that provides a view of exported directories | |
| | | only. A pseudo filesystem has a unique fsid and behaves like a | |
| | | normal, read only filesystem. | |
| | | | |
| | | Based on the construction of the server's name space, it is possible | |
| | | that multiple pseudo filesystems may exist. For example, | |
| | | | |
| | | /a pseudo filesystem | |
| | | /a/b real filesystem | |
| | | /a/b/c pseudo filesystem | |
| | | /a/b/c/d real filesystem | |
| | | Each of the pseudo filesystems are considered separate entities and | |
| | | therefore will have a unique fsid. | |
| | | | |
| | | 7.4. Multiple Roots | |
| | | | |
| | | The DOS and Windows operating environments are sometimes described as | |
| | | having "multiple roots". Filesystems are commonly represented as | |
| | | disk letters. MacOS represents filesystems as top level names. NFS | |
| | | version 4 servers for these platforms can construct a pseudo file | |
| | | system above these root names so that disk letters or volume names | |
| | | are simply directory names in the pseudo root. | |
| | | | |
| | | 7.5. Filehandle Volatility | |
| | | | |
| | | The nature of the server's pseudo filesystem is that it is a logical | |
| | | representation of filesystem(s) available from the server. | |
| | | Therefore, the pseudo filesystem is most likely constructed | |
| | | dynamically when the server is first instantiated. It is expected | |
| | | that the pseudo filesystem may not have an on disk counterpart from | |
| | | which persistent filehandles could be constructed. Even though it is | |
| | | preferable that the server provide persistent filehandles for the | |
| | | pseudo filesystem, the NFS client should expect that pseudo file | |
| | | system filehandles are volatile. This can be confirmed by checking | |
| | | the associated "fh_expire_type" attribute for those filehandles in | |
| | | question. If the filehandles are volatile, the NFS client must be | |
| | | prepared to recover a filehandle value (e.g., with a multi-component | |
| | | LOOKUP) when receiving an error of NFS4ERR_FHEXPIRED. | |
| | | | |
| | | 7.6. Exported Root | |
| | | | |
| | | If the server's root filesystem is exported, one might conclude that | |
| | | a pseudo-filesystem is not needed. This would be wrong. Assume the | |
| | | following filesystems on a server: | |
| | | | |
| | | / disk1 (exported) | |
| | | /a disk2 (not exported) | |
| | | /a/b disk3 (exported) | |
| | | | |
| | | Because disk2 is not exported, disk3 cannot be reached with simple | |
| | | LOOKUPs. The server must bridge the gap with a pseudo-filesystem. | |
| | | | |
| | | 7.7. Mount Point Crossing | |
| | | | |
| | | The server filesystem environment may be constructed in such a way | |
| | | that one filesystem contains a directory which is 'covered' or | |
| | | mounted upon by a second filesystem. For example: | |
| | | | |
| | | /a/b (filesystem 1) | |
| | | /a/b/c/d (filesystem 2) | |
| | | | |
| | | The pseudo filesystem for this server may be constructed to look | |
| | | like: | |
| | | | |
| | | / (place holder/not exported) | |
| | | /a/b (filesystem 1) | |
| | | /a/b/c/d (filesystem 2) | |
| | | | |
| | | It is the server's responsibility to present the pseudo filesystem | |
| | | that is complete to the client. If the client sends a lookup request | |
| | | for the path "/a/b/c/d", the server's response is the filehandle of | |
| | | the filesystem "/a/b/c/d". In previous versions of the NFS protocol, | |
| | | the server would respond with the filehandle of directory "/a/b/c/d" | |
| | | within the filesystem "/a/b". | |
| | | | |
| | | The NFS client will be able to determine if it crosses a server mount | |
| | | point by a change in the value of the "fsid" attribute. | |
| | | | |
| | | 7.8. Security Policy and Name Space Presentation | |
| | | | |
| | | The application of the server's security policy needs to be carefully | |
| | | considered by the implementor. One may choose to limit the | |
| | | viewability of portions of the pseudo filesystem based on the | |
| | | server's perception of the client's ability to authenticate itself | |
| | | properly. However, with the support of multiple security mechanisms | |
| | | and the ability to negotiate the appropriate use of these mechanisms, | |
| | | the server is unable to properly determine if a client will be able | |
| | | to authenticate itself. If, based on its policies, the server | |
| | | chooses to limit the contents of the pseudo filesystem, the server | |
| | | may effectively hide filesystems from a client that may otherwise | |
| | | have legitimate access. | |
| | | | |
| | | As suggested practice, the server should apply the security policy of | |
| | | a shared resource in the server's namespace to the components of the | |
| | | resource's ancestors. For example: | |
| | | | |
| | | / | |
| | | /a/b | |
| | | /a/b/c | |
| | | | |
| | | The /a/b/c directory is a real filesystem and is the shared resource. | |
| | | The security policy for /a/b/c is Kerberos with integrity. The | |
| | | server should apply the same security policy to /, /a, and /a/b. | |
| | | This allows for the extension of the protection of the server's | |
| | | namespace to the ancestors of the real shared resource. | |
| | | | |
| | | For the case of the use of multiple, disjoint security mechanisms in | |
| | | the server's resources, the security for a particular object in the | |
| | | server's namespace should be the union of all security mechanisms of | |
| | | all direct descendants. | |
| | | | |
| | | 8. File Locking and Share Reservations | |
| | | | |
| | | Integrating locking into the NFS protocol necessarily causes it to be | |
| | | stateful. With the inclusion of share reservations the protocol | |
| | | becomes substantially more dependent on state than the traditional | |
| | | combination of NFS and NLM [26]. There are three components to | |
| | | making this state manageable: | |
| | | | |
| | | o Clear division between client and server | |
| | | | |
| | | o Ability to reliably detect inconsistency in state between client | |
| | | and server | |
| | | | |
| | | o Simple and robust recovery mechanisms | |
| | | | |
| | | In this model, the server owns the state information. The client | |
| | | communicates its view of this state to the server as needed. The | |
| | | client is also able to detect inconsistent state before modifying a | |
| | | file. | |
| | | | |
| | | To support Win32 share reservations it is necessary to atomically | |
| | | OPEN or CREATE files. Having a separate share/unshare operation | |
| | | would not allow correct implementation of the Win32 OpenFile API. In | |
| | | order to correctly implement share semantics, the previous NFS | |
| | | protocol mechanisms used when a file is opened or created (LOOKUP, | |
| | | CREATE, ACCESS) need to be replaced. The NFS version 4 protocol has | |
| | | an OPEN operation that subsumes the NFS version 3 methodology of | |
| | | LOOKUP, CREATE, and ACCESS. However, because many operations require | |
| | | a filehandle, the traditional LOOKUP is preserved to map a file name | |
| | | to filehandle without establishing state on the server. The policy | |
| | | of granting access or modifying files is managed by the server based | |
| | | on the client's state. These mechanisms can implement policy ranging | |
| | | from advisory only locking to full mandatory locking. | |
| | | | |
| | | 8.1. Locking | |
| | | | |
| | | It is assumed that manipulating a lock is rare when compared to READ | |
| | | and WRITE operations. It is also assumed that crashes and network | |
| | | partitions are relatively rare. Therefore it is important that the | |
| | | READ and WRITE operations have a lightweight mechanism to indicate if | |
| | | they possess a held lock. A lock request contains the heavyweight | |
| | | information required to establish a lock and uniquely define the lock | |
| | | owner. | |
| | | | |
| | | The following sections describe the transition from the heavy weight | |
| | | information to the eventual stateid used for most client and server | |
| | | locking and lease interactions. | |
| | | | |
| | | 8.1.1. Client ID | |
| | | | |
| | | For each LOCK request, the client must identify itself to the server. | |
| | | | |
| | | This is done in such a way as to allow for correct lock | |
| | | identification and crash recovery. A sequence of a SETCLIENTID | |
| | | operation followed by a SETCLIENTID_CONFIRM operation is required to | |
| | | establish the identification onto the server. Establishment of | |
| | | identification by a new incarnation of the client also has the effect | |
| | | of immediately breaking any leased state that a previous incarnation | |
| | | of the client might have had on the server, as opposed to forcing the | |
| | | new client incarnation to wait for the leases to expire. Breaking | |
| | | the lease state amounts to the server removing all lock, share | |
| | | reservation, and, where the server is not supporting the | |
| | | CLAIM_DELEGATE_PREV claim type, all delegation state associated with | |
| | | same client with the same identity. For discussion of delegation | |
| | | state recovery, see Section 9.2.1 "Delegation Recovery". | |
| | | | |
| | | Client identification is encapsulated in the following structure: | |
| | | | |
| | | struct SETCLIENTID4args { | |
| | | nfs_client_id4 client; | |
| | | cb_client4 callback; | |
| | | uint32_t callback_ident; | |
| | | }; | |
| | | | |
| | | The first field, verifier is a client incarnation verifier that is | |
| | | used to detect client reboots. Only if the verifier is different | |
| | | from that which the server has previously recorded the client (as | |
| | | identified by the second field of the structure, id) does the server | |
| | | start the process of canceling the client's leased state. | |
| | | | |
| | | The second field, id is a variable length string that uniquely | |
| | | defines the client. | |
| | | | |
| | | There are several considerations for how the client generates the id | |
| | | string: | |
| | | | |
| | | o The string should be unique so that multiple clients do not | |
| | | present the same string. The consequences of two clients | |
| | | presenting the same string range from one client getting an error | |
| | | to one client having its leased state abruptly and unexpectedly | |
| | | canceled. | |
| | | | |
| | | o The string should be selected so the subsequent incarnations | |
| | | (e.g., reboots) of the same client cause the client to present the | |
| | | same string. The implementor is cautioned against an approach | |
| | | that requires the string to be recorded in a local file because | |
| | | this precludes the use of the implementation in an environment | |
| | | where there is no local disk and all file access is from an NFS | |
| | | version 4 server. | |
| | | | |
| | | o The string should be different for each server network address | |
| | | that the client accesses, rather than common to all server network | |
| | | addresses. The reason is that it may not be possible for the | |
| | | client to tell if the same server is listening on multiple network | |
| | | addresses. If the client issues SETCLIENTID with the same id | |
| | | string to each network address of such a server, the server will | |
| | | think it is the same client, and each successive SETCLIENTID will | |
| | | cause the server to begin the process of removing the client's | |
| | | previous leased state. | |
| | | | |
| | | o The algorithm for generating the string should not assume that the | |
| | | client's network address won't change. This includes changes | |
| | | between client incarnations and even changes while the client is | |
| | | stilling running in its current incarnation. This means that if | |
| | | the client includes just the client's and server's network address | |
| | | in the id string, there is a real risk, after the client gives up | |
| | | the network address, that another client, using a similar | |
| | | algorithm for generating the id string, will generate a | |
| | | conflicting id string. | |
| | | | |
| | | Given the above considerations, an example of a well generated id | |
| | | string is one that includes: | |
| | | | |
| | | o The server's network address. | |
| | | | |
| | | o The client's network address. | |
| | | | |
| | | o For a user level NFS version 4 client, it should contain | |
| | | additional information to distinguish the client from other user | |
| | | level clients running on the same host, such as a process id or | |
| | | other unique sequence. | |
| | | | |
| | | o Additional information that tends to be unique, such as one or | |
| | | more of: | |
| | | | |
| | | * The client machine's serial number (for privacy reasons, it is | |
| | | best to perform some one way function on the serial number). | |
| | | | |
| | | * A MAC address. | |
| | | | |
| | | * The timestamp of when the NFS version 4 software was first | |
| | | installed on the client (though this is subject to the | |
| | | previously mentioned caution about using information that is | |
| | | stored in a file, because the file might only be accessible | |
| | | over NFS version 4). | |
| | | | |
| | | * A true random number. However since this number ought to be | |
| | | the same between client incarnations, this shares the same | |
| | | problem as that of the using the timestamp of the software | |
| | | installation. | |
| | | | |
| | | As a security measure, the server MUST NOT cancel a client's leased | |
| | | state if the principal established the state for a given id string is | |
| | | not the same as the principal issuing the SETCLIENTID. | |
| | | | |
| | | Note that SETCLIENTID and SETCLIENTID_CONFIRM has a secondary purpose | |
| | | of establishing the information the server needs to make callbacks to | |
| | | the client for purpose of supporting delegations. It is permitted to | |
| | | change this information via SETCLIENTID and SETCLIENTID_CONFIRM | |
| | | within the same incarnation of the client without removing the | |
| | | client's leased state. | |
| | | | |
| | | Once a SETCLIENTID and SETCLIENTID_CONFIRM sequence has successfully | |
| | | completed, the client uses the shorthand client identifier, of type | |
| | | clientid4, instead of the longer and less compact nfs_client_id4 | |
| | | structure. This shorthand client identifier (a clientid) is assigned | |
| | | by the server and should be chosen so that it will not conflict with | |
| | | a clientid previously assigned by the server. This applies across | |
| | | server restarts or reboots. When a clientid is presented to a server | |
| | | and that clientid is not recognized, as would happen after a server | |
| | | reboot, the server will reject the request with the error | |
| | | NFS4ERR_STALE_CLIENTID. When this happens, the client must obtain a | |
| | | new clientid by use of the SETCLIENTID operation and then proceed to | |
| | | any other necessary recovery for the server reboot case (See | |
| | | Section 8.6.2 "Server Failure and Recovery"). | |
| | | | |
| | | The client must also employ the SETCLIENTID operation when it | |
| | | receives a NFS4ERR_STALE_STATEID error using a stateid derived from | |
| | | its current clientid, since this also indicates a server reboot which | |
| | | has invalidated the existing clientid (see Section 8.1.3 "lock_owner | |
| | | and stateid Definition" for details). | |
| | | | |
| | | See the detailed descriptions of SETCLIENTID and SETCLIENTID_CONFIRM | |
| | | |