draft-ietf-nfsv4-rfc3530bis-16.txt | draft-ietf-nfsv4-rfc3530bis-17.txt | |||
---|---|---|---|---|
NFSv4 T. Haynes, Ed. | NFSv4 T. Haynes, Ed. | |||
Internet-Draft NetApp | Internet-Draft NetApp | |||
Intended status: Standards Track D. Noveck, Ed. | Intended status: Standards Track D. Noveck, Ed. | |||
Expires: May 2, 2012 EMC | Expires: September 13, 2012 EMC | |||
October 30, 2011 | March 12, 2012 | |||
Network File System (NFS) Version 4 Protocol | Network File System (NFS) Version 4 Protocol | |||
draft-ietf-nfsv4-rfc3530bis-16.txt | draft-ietf-nfsv4-rfc3530bis-17.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 1, line 49 | skipping to change at page 1, line 49 | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at http://datatracker.ietf.org/drafts/current/. | Drafts is at http://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on May 2, 2012. | This Internet-Draft will expire on September 13, 2012. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2011 IETF Trust and the persons identified as the | Copyright (c) 2012 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(http://trustee.ietf.org/license-info) in effect on the date of | (http://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
skipping to change at page 5, line 26 | skipping to change at page 5, line 26 | |||
9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 115 | 9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 115 | |||
9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 117 | 9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 117 | |||
9.1.7. Recovery from Replayed Requests . . . . . . . . . . 118 | 9.1.7. Recovery from Replayed Requests . . . . . . . . . . 118 | |||
9.1.8. Interactions of multiple sequence values . . . . . . 118 | 9.1.8. Interactions of multiple sequence values . . . . . . 118 | |||
9.1.9. Releasing state-owner State . . . . . . . . . . . . 119 | 9.1.9. Releasing state-owner State . . . . . . . . . . . . 119 | |||
9.1.10. Use of Open Confirmation . . . . . . . . . . . . . . 120 | 9.1.10. Use of Open Confirmation . . . . . . . . . . . . . . 120 | |||
9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 121 | 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 121 | |||
9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 121 | 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 121 | |||
9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 122 | 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 122 | |||
9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 123 | 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 123 | |||
9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 123 | 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 124 | |||
9.6.1. Client Failure and Recovery . . . . . . . . . . . . 124 | 9.6.1. Client Failure and Recovery . . . . . . . . . . . . 124 | |||
9.6.2. Server Failure and Recovery . . . . . . . . . . . . 124 | 9.6.2. Server Failure and Recovery . . . . . . . . . . . . 124 | |||
9.6.3. Network Partitions and Recovery . . . . . . . . . . 126 | 9.6.3. Network Partitions and Recovery . . . . . . . . . . 126 | |||
9.7. Recovery from a Lock Request Timeout or Abort . . . . . 132 | 9.7. Recovery from a Lock Request Timeout or Abort . . . . . 134 | |||
9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 133 | 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 134 | |||
9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 134 | 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 136 | |||
9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 135 | 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 136 | |||
9.10.1. Close and Retention of State Information . . . . . . 136 | 9.10.1. Close and Retention of State Information . . . . . . 137 | |||
9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 136 | 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 138 | |||
9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 137 | 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 138 | |||
9.13. Clocks, Propagation Delay, and Calculating Lease | 9.13. Clocks, Propagation Delay, and Calculating Lease | |||
Expiration . . . . . . . . . . . . . . . . . . . . . . . 137 | Expiration . . . . . . . . . . . . . . . . . . . . . . . 139 | |||
9.14. Migration, Replication and State . . . . . . . . . . . . 138 | 9.14. Migration, Replication and State . . . . . . . . . . . . 139 | |||
9.14.1. Migration and State . . . . . . . . . . . . . . . . 138 | 9.14.1. Migration and State . . . . . . . . . . . . . . . . 140 | |||
9.14.2. Replication and State . . . . . . . . . . . . . . . 139 | 9.14.2. Replication and State . . . . . . . . . . . . . . . 141 | |||
9.14.3. Notification of Migrated Lease . . . . . . . . . . . 140 | 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 141 | |||
9.14.4. Migration and the Lease_time Attribute . . . . . . . 141 | 9.14.4. Migration and the Lease_time Attribute . . . . . . . 142 | |||
10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 141 | 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 142 | |||
10.1. Performance Challenges for Client-Side Caching . . . . . 142 | 10.1. Performance Challenges for Client-Side Caching . . . . . 143 | |||
10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 143 | 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 144 | |||
10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 144 | 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 146 | |||
10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 146 | 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 150 | |||
10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 147 | 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 150 | |||
10.3.2. Data Caching and File Locking . . . . . . . . . . . 148 | 10.3.2. Data Caching and File Locking . . . . . . . . . . . 151 | |||
10.3.3. Data Caching and Mandatory File Locking . . . . . . 149 | 10.3.3. Data Caching and Mandatory File Locking . . . . . . 153 | |||
10.3.4. Data Caching and File Identity . . . . . . . . . . . 150 | 10.3.4. Data Caching and File Identity . . . . . . . . . . . 153 | |||
10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 151 | 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 154 | |||
10.4.1. Open Delegation and Data Caching . . . . . . . . . . 153 | 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 157 | |||
10.4.2. Open Delegation and File Locks . . . . . . . . . . . 154 | 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 158 | |||
10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 155 | 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 158 | |||
10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 158 | 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 161 | |||
10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 160 | 10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 163 | |||
10.4.6. Clients that Fail to Honor Delegation Recalls . . . 160 | 10.4.6. Clients that Fail to Honor Delegation Recalls . . . 164 | |||
10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 161 | 10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 165 | |||
10.5. Data Caching and Revocation . . . . . . . . . . . . . . 162 | 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 165 | |||
10.5.1. Revocation Recovery for Write Open Delegation . . . 162 | 10.5.1. Revocation Recovery for Write Open Delegation . . . 166 | |||
10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 163 | 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 167 | |||
10.7. Data and Metadata Caching and Memory Mapped Files . . . 165 | 10.7. Data and Metadata Caching and Memory Mapped Files . . . 169 | |||
10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 167 | 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 171 | |||
10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 168 | 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 172 | |||
11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 169 | 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 173 | |||
12. Internationalization . . . . . . . . . . . . . . . . . . . . 172 | 12. Internationalization . . . . . . . . . . . . . . . . . . . . 175 | |||
12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 173 | 12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 176 | |||
12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 173 | 12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 176 | |||
12.1.2. Normalization, Equivalence, and Confusability . . . 174 | 12.1.2. Normalization, Equivalence, and Confusability . . . 177 | |||
12.2. String Type Overview . . . . . . . . . . . . . . . . . . 176 | 12.2. String Type Overview . . . . . . . . . . . . . . . . . . 180 | |||
12.2.1. Overall String Class Divisions . . . . . . . . . . . 177 | 12.2.1. Overall String Class Divisions . . . . . . . . . . . 180 | |||
12.2.2. Divisions by Typedef Parent types . . . . . . . . . 178 | 12.2.2. Divisions by Typedef Parent types . . . . . . . . . 181 | |||
12.2.3. Individual Types and Their Handling . . . . . . . . 178 | 12.2.3. Individual Types and Their Handling . . . . . . . . 182 | |||
12.3. Errors Related to Strings . . . . . . . . . . . . . . . 180 | 12.3. Errors Related to Strings . . . . . . . . . . . . . . . 183 | |||
12.4. Types with Pre-processing to Resolve Mixture Issues . . 181 | 12.4. Types with Pre-processing to Resolve Mixture Issues . . 184 | |||
12.4.1. Processing of Principal Strings . . . . . . . . . . 181 | 12.4.1. Processing of Principal Strings . . . . . . . . . . 184 | |||
12.4.2. Processing of Server Id Strings . . . . . . . . . . 181 | 12.4.2. Processing of Server Id Strings . . . . . . . . . . 185 | |||
12.5. String Types without Internationalization Processing . . 182 | 12.5. String Types without Internationalization Processing . . 185 | |||
12.6. Types with Processing Defined by Other Internet Areas . 182 | 12.6. Types with Processing Defined by Other Internet Areas . 186 | |||
12.7. String Types with NFS-specific Processing . . . . . . . 183 | 12.7. String Types with NFS-specific Processing . . . . . . . 187 | |||
12.7.1. Handling of File Name Components . . . . . . . . . . 184 | 12.7.1. Handling of File Name Components . . . . . . . . . . 187 | |||
12.7.2. Processing of Link Text . . . . . . . . . . . . . . 193 | 12.7.2. Processing of Link Text . . . . . . . . . . . . . . 196 | |||
12.7.3. Processing of Principal Prefixes . . . . . . . . . . 194 | 12.7.3. Processing of Principal Prefixes . . . . . . . . . . 197 | |||
13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 195 | 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 198 | |||
13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 195 | 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 198 | |||
13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 196 | 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 200 | |||
13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 198 | 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 201 | |||
13.1.3. Compound Structure Errors . . . . . . . . . . . . . 199 | 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 203 | |||
13.1.4. File System Errors . . . . . . . . . . . . . . . . . 200 | 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 203 | |||
13.1.5. State Management Errors . . . . . . . . . . . . . . 202 | 13.1.5. State Management Errors . . . . . . . . . . . . . . 205 | |||
13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 203 | 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 206 | |||
13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 203 | 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 207 | |||
13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 204 | 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 208 | |||
13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 205 | 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 209 | |||
13.1.10. Client Management Errors . . . . . . . . . . . . . . 206 | 13.1.10. Client Management Errors . . . . . . . . . . . . . . 210 | |||
13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 206 | 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 210 | |||
13.2. Operations and their valid errors . . . . . . . . . . . 207 | 13.2. Operations and their valid errors . . . . . . . . . . . 211 | |||
13.3. Callback operations and their valid errors . . . . . . . 214 | 13.3. Callback operations and their valid errors . . . . . . . 218 | |||
13.4. Errors and the operations that use them . . . . . . . . 214 | 13.4. Errors and the operations that use them . . . . . . . . 218 | |||
14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 219 | 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 223 | |||
14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 219 | 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 223 | |||
14.2. Evaluation of a Compound Request . . . . . . . . . . . . 220 | 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 224 | |||
14.3. Synchronous Modifying Operations . . . . . . . . . . . . 221 | 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 225 | |||
14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 221 | 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 225 | |||
15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 221 | 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 225 | |||
15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 221 | 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 225 | |||
15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 222 | 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 226 | |||
15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 225 | 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 229 | |||
15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 228 | 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 232 | |||
15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 229 | 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 233 | |||
15.6. Operation 6: CREATE - Create a Non-Regular File Object . 232 | 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 236 | |||
15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting | 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting | |||
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 234 | Recovery . . . . . . . . . . . . . . . . . . . . . . . . 238 | |||
15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 235 | 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 240 | |||
15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 236 | 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 240 | |||
15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 238 | 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 242 | |||
15.11. Operation 11: LINK - Create Link to a File . . . . . . . 239 | 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 243 | |||
15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 240 | 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 245 | |||
15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 244 | 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 249 | |||
15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 246 | 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 251 | |||
15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 247 | 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 252 | |||
15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 249 | 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 254 | |||
15.17. Operation 17: NVERIFY - Verify Difference in | 15.17. Operation 17: NVERIFY - Verify Difference in | |||
Attributes . . . . . . . . . . . . . . . . . . . . . . . 250 | Attributes . . . . . . . . . . . . . . . . . . . . . . . 255 | |||
15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 251 | 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 256 | |||
15.19. Operation 19: OPENATTR - Open Named Attribute | 15.19. Operation 19: OPENATTR - Open Named Attribute | |||
Directory . . . . . . . . . . . . . . . . . . . . . . . 261 | Directory . . . . . . . . . . . . . . . . . . . . . . . 266 | |||
15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 262 | 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 267 | |||
15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 264 | 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 269 | |||
15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 265 | 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 270 | |||
15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 266 | 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 271 | |||
15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 268 | 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 272 | |||
15.25. Operation 25: READ - Read from File . . . . . . . . . . 268 | 15.25. Operation 25: READ - Read from File . . . . . . . . . . 273 | |||
15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 270 | 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 275 | |||
15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 274 | 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 279 | |||
15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 275 | 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 280 | |||
15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 277 | 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 282 | |||
15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 279 | 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 284 | |||
15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 280 | 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 285 | |||
15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 281 | 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 286 | |||
15.33. Operation 33: SECINFO - Obtain Available Security . . . 282 | 15.33. Operation 33: SECINFO - Obtain Available Security . . . 287 | |||
15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 285 | 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 290 | |||
15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 288 | 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 293 | |||
15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 292 | 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 297 | |||
15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 295 | 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 300 | |||
15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 297 | 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 302 | |||
15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner | 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner | |||
State . . . . . . . . . . . . . . . . . . . . . . . . . 301 | State . . . . . . . . . . . . . . . . . . . . . . . . . 306 | |||
15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 302 | 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 307 | |||
16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 303 | 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 308 | |||
16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 303 | 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 308 | |||
16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 303 | 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 308 | |||
16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 305 | 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 310 | |||
16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 306 | 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 311 | |||
16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback | 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback | |||
Operation . . . . . . . . . . . . . . . . . . . . . 307 | Operation . . . . . . . . . . . . . . . . . . . . . 312 | |||
17. Security Considerations . . . . . . . . . . . . . . . . . . . 308 | 17. Security Considerations . . . . . . . . . . . . . . . . . . . 313 | |||
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 310 | 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 315 | |||
18.1. Named Attribute Definitions . . . . . . . . . . . . . . 310 | 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 315 | |||
18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 311 | 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 316 | |||
18.1.2. Updating Registrations . . . . . . . . . . . . . . . 311 | 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 316 | |||
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 311 | 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 316 | |||
19.1. Normative References . . . . . . . . . . . . . . . . . . 311 | 19.1. Normative References . . . . . . . . . . . . . . . . . . 316 | |||
19.2. Informative References . . . . . . . . . . . . . . . . . 312 | 19.2. Informative References . . . . . . . . . . . . . . . . . 317 | |||
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 314 | Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 319 | |||
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 315 | Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 320 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 315 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 320 | |||
1. Introduction | 1. Introduction | |||
1.1. Changes since RFC 3530 | 1.1. Changes since RFC 3530 | |||
This document, together with the companion XDR description document | This document, together with the companion XDR description document | |||
[2], obsoletes RFC 3530 [11] as the authoritative document describing | [2], obsoletes RFC 3530 [11] as the authoritative document describing | |||
NFSv4. It does not introduce any over-the-wire protocol changes, in | NFSv4. It does not introduce any over-the-wire protocol changes, in | |||
the sense that previously valid requests requests remain valid. | the sense that previously valid requests requests remain valid. | |||
However, some requests previously defined as invalid, although not | However, some requests previously defined as invalid, although not | |||
skipping to change at page 50, line 25 | skipping to change at page 50, line 25 | |||
translation is available while using the local representation for | translation is available while using the local representation for | |||
those cases in which a translation is available. | those cases in which a translation is available. | |||
Servers that do not provide support for all possible values of the | Servers that do not provide support for all possible values of the | |||
owner and owner_group attributes SHOULD return an error | owner and owner_group attributes SHOULD return an error | |||
(NFS4ERR_BADOWNER) when a string is presented that has no | (NFS4ERR_BADOWNER) when a string is presented that has no | |||
translation, as the value to be set for a SETATTR of the owner, | 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 | 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 | 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 | owner and group strings in an acl), it is promising to return that | |||
same string for which see below) when a corresponding GETATTR is | same string (for which see below) when a corresponding GETATTR is | |||
done. For some internationalization-related exceptions where this is | done. For some internationalization-related exceptions where this is | |||
not possible, see below. Configuration changes (including changes | not possible, see below. Configuration changes (including changes | |||
from the mapping of the string to the local representation) and ill- | from the mapping of the string to the local representation) and ill- | |||
constructed name translations (those that contain aliasing) may make | constructed name translations (those that contain aliasing) may make | |||
that promise impossible to honor. Servers should make appropriate | that promise impossible to honor. Servers should make appropriate | |||
efforts to avoid a situation in which these attributes have their | efforts to avoid a situation in which these attributes have their | |||
values changed when no real change to ownership has occurred. | values changed when no real change to ownership has occurred. | |||
The "dns_domain" portion of the owner string is meant to be a DNS | The "dns_domain" portion of the owner string is meant to be a DNS | |||
domain name. For example, user@example.org. Servers should accept | domain name. For example, user@example.org. Servers should accept | |||
skipping to change at page 112, line 49 | skipping to change at page 112, line 49 | |||
o If the table index field is outside the range of the associated | o If the table index field is outside the range of the associated | |||
table, return NFS4ERR_BAD_STATEID. | table, return NFS4ERR_BAD_STATEID. | |||
o If the selected table entry is of a different generation than that | o If the selected table entry is of a different generation than that | |||
specified in the incoming stateid, return NFS4ERR_BAD_STATEID. | specified in the incoming stateid, return NFS4ERR_BAD_STATEID. | |||
o If the selected table entry does not match the current filehandle, | o If the selected table entry does not match the current filehandle, | |||
return NFS4ERR_BAD_STATEID. | return NFS4ERR_BAD_STATEID. | |||
o If the stateid represents revoked state, then return | o If the stateid represents revoked state or state lost as a result | |||
NFS4ERR_EXPIRED or NFS4ERR_ADMIN_REVOKED, as appropriate. | of lease expiration, then return NFS4ERR_EXPIRED, | |||
NFS4ERR_BAD_STATEID, or NFS4ERR_ADMIN_REVOKED, as appropriate. | ||||
o If the stateid type is not valid for the context in which the | o If the stateid type is not valid for the context in which the | |||
stateid appears, return NFS4ERR_BAD_STATEID. Note that a stateid | stateid appears, return NFS4ERR_BAD_STATEID. Note that a stateid | |||
may be valid in general, but be invalid for a particular | may be valid in general, but be invalid for a particular | |||
operation, as, for example, when a stateid which doesn't represent | operation, as, for example, when a stateid which doesn't represent | |||
byte-range locks is passed to the non-from_open case of LOCK or to | byte-range locks is passed to the non-from_open case of LOCK or to | |||
LOCKU, or when a stateid which does not represent an open is | LOCKU, or when a stateid which does not represent an open is | |||
passed to CLOSE or OPEN_DOWNGRADE. In such cases, the server MUST | passed to CLOSE or OPEN_DOWNGRADE. In such cases, the server MUST | |||
return NFS4ERR_BAD_STATEID. | return NFS4ERR_BAD_STATEID. | |||
skipping to change at page 118, line 50 | skipping to change at page 118, line 50 | |||
As noted above, there may be multiple sequence values to check. The | As noted above, there may be multiple sequence values to check. The | |||
following rules should be followed by the server in processing these | following rules should be followed by the server in processing these | |||
multiple sequence values within a single operation. | multiple sequence values within a single operation. | |||
o When a sequence value associated with a state-owner is unavailable | o When a sequence value associated with a state-owner is unavailable | |||
for checking because the state-owner is unknown to the server, it | for checking because the state-owner is unknown to the server, it | |||
takes no part in the comparison. | takes no part in the comparison. | |||
o When any of the state-owner sequence values are invalid, | o When any of the state-owner sequence values are invalid, | |||
NFS4ERR_BADSEQ is returned. When a stateid sequence is checked, | NFS4ERR_BAD_SEQID is returned. When a stateid sequence is | |||
NFS4ERR_BAD_STATEID, or NFS4ERR_OLDSTATEID is returned as | checked, NFS4ERR_BAD_STATEID, or NFS4ERR_OLD_STATEID is returned | |||
appropriate, but NFS4ERR_BADSEQ has priority. | as appropriate, but NFS4ERR_BAD_SEQID has priority. | |||
o When any one of the sequence values matches a previous request, | o When any one of the sequence values matches a previous request, | |||
for a state-owner, it is treated as a retransmission and not re- | for a state-owner, it is treated as a retransmission and not re- | |||
executed. When the type of the operation does not match that | executed. When the type of the operation does not match that | |||
originally used, NFS4ERR_BADSEQ is returned. When the server can | originally used, NFS4ERR_BAD_SEQID is returned. When the server | |||
determine that the request differs from the original it may return | can determine that the request differs from the original it may | |||
NFS4ERR_BADSEQ. | return NFS4ERR_BAD_SEQID. | |||
o When multiple of the sequence values match previous operations, | o When multiple of the sequence values match previous operations, | |||
but the operations are not the same, NFS4ERR_BADSEQ is returned. | but the operations are not the same, NFS4ERR_BAD_SEQID is | |||
returned. | ||||
o When there are no available sequence values available for | o When there are no available sequence values available for | |||
comparison and the operation is an OPEN, the server indicates to | comparison and the operation is an OPEN, the server indicates to | |||
the client that an OPEN_CONFIRM is required, unless it can | the client that an OPEN_CONFIRM is required, unless it can | |||
conclusively determine that confirmation is not required (e.g., by | conclusively determine that confirmation is not required (e.g., by | |||
knowing that no open-owner state has ever been released for the | knowing that no open-owner state has ever been released for the | |||
current clientid). | current clientid). | |||
9.1.9. Releasing state-owner State | 9.1.9. Releasing state-owner State | |||
skipping to change at page 121, line 11 | skipping to change at page 121, line 13 | |||
type opens poses difficulties in that the inability to resolve the | type opens poses difficulties in that the inability to resolve the | |||
status of the reclaim until lease expiration may make it difficult to | status of the reclaim until lease expiration may make it difficult to | |||
have timely determination of the set of locks being reclaimed (since | have timely determination of the set of locks being reclaimed (since | |||
the grace period may expire). | the grace period may expire). | |||
Requiring open confirmation on reclaim-type opens is avoidable | Requiring open confirmation on reclaim-type opens is avoidable | |||
because of the nature of the environments in which such opens are | because of the nature of the environments in which such opens are | |||
done. For CLAIM_PREVIOUS opens, this is immediately after server | done. For CLAIM_PREVIOUS opens, this is immediately after server | |||
reboot, so there should be no time for open-owners to be created, | reboot, so there should be no time for open-owners to be created, | |||
found to be unused, and recycled. For CLAIM_DELEGATE_PREV opens, we | found to be unused, and recycled. For CLAIM_DELEGATE_PREV opens, we | |||
are dealing with a client reboot situation. A server which supports | are dealing with either a client reboot situation or a network | |||
delegation can be sure that no open-owners for that client have been | partition resulting in deletion of lease state (and returning | |||
recycled since client initialization and thus can ensure that | NFS4ERR_EXPIRED). A server which supports delegations can be sure | |||
that no open-owners for that client have been recycled since client | ||||
initialization or deletion of lease state and thus can ensure that | ||||
confirmation will not be required. | confirmation will not be required. | |||
9.2. Lock Ranges | 9.2. Lock Ranges | |||
The protocol allows a lock owner to request a lock with a byte range | The protocol allows a lock owner to request a lock with a byte range | |||
and then either upgrade or unlock a sub-range of the initial lock. | and then either upgrade or unlock a sub-range of the initial lock. | |||
It is expected that this will be an uncommon type of request. In any | It is expected that this will be an uncommon type of request. In any | |||
case, servers or server filesystems may not be able to support sub- | case, servers or server filesystems may not be able to support sub- | |||
range lock semantics. In the event that a server receives a locking | range lock semantics. In the event that a server receives a locking | |||
request that represents a sub-range of current locking state for the | request that represents a sub-range of current locking state for the | |||
skipping to change at page 123, line 20 | skipping to change at page 123, line 24 | |||
renewals may not be denied if the lease interval has not expired. | renewals may not be denied if the lease interval has not expired. | |||
The following events cause implicit renewal of all of the leases for | The following events cause implicit renewal of all of the leases for | |||
a given client (i.e., all those sharing a given client ID). Each of | a given client (i.e., all those sharing a given client ID). Each of | |||
these is a positive indication that the client is still active and | these is a positive indication that the client is still active and | |||
that the associated state held at the server, for the client, is | that the associated state held at the server, for the client, is | |||
still valid. | still valid. | |||
o An OPEN with a valid client ID. | o An OPEN with a valid client ID. | |||
o Any operation made with a valid stateid (CLOSE, DELEGPURGE, | o Any operation made with a valid clientid (DELEGPURGE, RENEW, OPEN, | |||
DELEGRETURN, LOCK, LOCKU, OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE, | LOCK) or a valid stateid (CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, | |||
READ, RENEW, SETATTR, or WRITE). This does not include the | OPEN_CONFIRM, OPEN_DOWNGRADE, READ, SETATTR, or WRITE). In the | |||
special stateids of all bits 0 or all bits 1. | latter case, the stateid must not be one of the special stateids | |||
consisting of all bits 0 or all bits 1. | ||||
Note that if the client had restarted or rebooted, the client | Note that if the client had restarted or rebooted, the client | |||
would not be making these requests without issuing the | would not be making these requests without issuing the | |||
SETCLIENTID/SETCLIENTID_CONFIRM sequence. The use of the | SETCLIENTID/SETCLIENTID_CONFIRM sequence. The use of the | |||
SETCLIENTID/SETCLIENTID_CONFIRM sequence (one that changes the | SETCLIENTID/SETCLIENTID_CONFIRM sequence (one that changes the | |||
client verifier) notifies the server to drop the locking state | client verifier) notifies the server to drop the locking state | |||
associated with the client. SETCLIENTID/SETCLIENTID_CONFIRM never | associated with the client. SETCLIENTID/SETCLIENTID_CONFIRM never | |||
renews a lease. | renews a lease. | |||
If the server has rebooted, the stateids (NFS4ERR_STALE_STATEID | If the server has rebooted, the stateids (NFS4ERR_STALE_STATEID | |||
skipping to change at page 125, line 18 | skipping to change at page 125, line 23 | |||
reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a | reboot or restart. The NFS4ERR_STALE_CLIENTID error indicates a | |||
client ID invalidated by reboot or restart. When either of these are | client ID invalidated by reboot or restart. When either of these are | |||
received, the client must establish a new client ID (see | received, the client must establish a new client ID (see | |||
Section 9.1.1) and re-establish the locking state as discussed below. | Section 9.1.1) and re-establish the locking state as discussed below. | |||
The period of special handling of locking and READs and WRITEs, equal | The period of special handling of locking and READs and WRITEs, equal | |||
in duration to the lease period, is referred to as the "grace | in duration to the lease period, is referred to as the "grace | |||
period". During the grace period, clients recover locks and the | period". During the grace period, clients recover locks and the | |||
associated state by reclaim-type locking requests (i.e., LOCK | associated state by reclaim-type locking requests (i.e., LOCK | |||
requests with reclaim set to true and OPEN operations with a claim | requests with reclaim set to true and OPEN operations with a claim | |||
type of CLAIM_PREVIOUS). During the grace period, the server must | type of either CLAIM_PREVIOUS or CLAIM_DELEGATE_PREV). During the | |||
reject READ and WRITE operations and non-reclaim locking requests | grace period, the server must reject READ and WRITE operations and | |||
(i.e., other LOCK and OPEN operations) with an error of | non-reclaim locking requests (i.e., other LOCK and OPEN operations) | |||
NFS4ERR_GRACE. | with an error of NFS4ERR_GRACE. | |||
If the server can reliably determine that granting a non-reclaim | If the server can reliably determine that granting a non-reclaim | |||
request will not conflict with reclamation of locks by other clients, | request will not conflict with reclamation of locks by other clients, | |||
the NFS4ERR_GRACE error does not have to be returned and the non- | the NFS4ERR_GRACE error does not have to be returned and the non- | |||
reclaim client request can be serviced. For the server to be able to | reclaim client request can be serviced. For the server to be able to | |||
service READ and WRITE operations during the grace period, it must | service READ and WRITE operations during the grace period, it must | |||
again be able to guarantee that no possible conflict could arise | again be able to guarantee that no possible conflict could arise | |||
between an impending reclaim locking request and the READ or WRITE | between an impending reclaim locking request and the READ or WRITE | |||
operation. If the server is unable to offer that guarantee, the | operation. If the server is unable to offer that guarantee, the | |||
NFS4ERR_GRACE error must be returned to the client. | NFS4ERR_GRACE error must be returned to the client. | |||
skipping to change at page 126, line 34 | skipping to change at page 126, line 40 | |||
for lease renewal for the lease associated with that server. | for lease renewal for the lease associated with that server. | |||
However, the server must establish, for this restart event, a grace | However, the server must establish, for this restart event, a grace | |||
period at least as long as the lease period for the previous server | period at least as long as the lease period for the previous server | |||
instantiation. This allows the client state obtained during the | instantiation. This allows the client state obtained during the | |||
previous server instance to be reliably re-established. | previous server instance to be reliably re-established. | |||
9.6.3. Network Partitions and Recovery | 9.6.3. Network Partitions and Recovery | |||
If the duration of a network partition is greater than the lease | If the duration of a network partition is greater than the lease | |||
period provided by the server, the server will have not received a | period provided by the server, the server will have not received a | |||
lease renewal from the client. If this occurs, the server may free | lease renewal from the client. If this occurs, the server may cancel | |||
all locks held for the client. As a result, all stateids held by the | the lease and free all locks held for the client. As a result, all | |||
client will become invalid or stale. Once the client is able to | stateids held by the client will become invalid or stale. Once the | |||
reach the server after such a network partition, all I/O submitted by | client is able to reach the server after such a network partition, | |||
the client with the now invalid stateids will fail with the server | all I/O submitted by the client with the now invalid stateids will | |||
returning the error NFS4ERR_EXPIRED. Once this error is received, | fail with the server returning the error NFS4ERR_EXPIRED. Once this | |||
the client will suitably notify the application that held the lock. | error is received, the client will suitably notify the application | |||
that held the lock. | ||||
9.6.3.1. Courtesy Locks | 9.6.3.1. Courtesy Locks | |||
As a courtesy to the client or as an optimization, the server may | As a courtesy to the client or as an optimization, the server may | |||
continue to hold locks on behalf of a client for which recent | continue to hold locks, including delegations, on behalf of a client | |||
communication has extended beyond the lease period. If the server | for which recent communication has extended beyond the lease period, | |||
receives a lock or I/O request that conflicts with one of these | delaying the cancellation of the lease. If the server receives a | |||
courtesy locks, the server MUST free the courtesy lock and grant the | lock or I/O request that conflicts with one of these courtesy locks | |||
new request. If the server runs out of resources, it MAY free all | or if it runs out of resources, the server MAY cause lease | |||
courtesy locks. I.e., the client MUST not make an assumption that | cancellation to occur at that time and henceforth return | |||
the server has issued courtesy locks. | NFS4ERR_EXPIRED when any of the stateids associated with the freed | |||
locks is used. If lease cancellation has not occurred and the server | ||||
receives a lock or I/O request that conflicts with one of the | ||||
courtesy locks, the requirements are as follows: | ||||
If the server does not reboot before the network partition is healed, | o In the case of a courtesy lock which is not a delegation, it MUST | |||
when the original client tries to access a courtesy lock which was | free the courtesy lock and grant the new request. | |||
freed, the server SHOULD send back a NFS4ERR_BAD_STATEID to the | ||||
client. If the client tries to access a courtesy lock which was not | o In the case of lock or IO request which conflicts with a | |||
freed, then the server SHOULD mark all of the courtesy locks as | delegation which is being held as courtesy lock, the server MAY | |||
implicitly being renewed. | delay resolution of request but MUST NOT reject the request and | |||
MUST free the delegation and grant the new request eventually. | ||||
o In the case of a requests for a delegation which conflicts with a | ||||
delegation which is being held as courtesy lock, the server MAY | ||||
grant the new request or not as it chooses, but if it grants the | ||||
conflicting request, the delegation haled as courtesy lock MUST be | ||||
freed. | ||||
If the server does not reboot or cancel the lease before the network | ||||
partition is healed, when the original client tries to access a | ||||
courtesy lock which was freed, the server SHOULD send back a | ||||
NFS4ERR_BAD_STATEID to the client. If the client tries to access a | ||||
courtesy lock which was not freed, then the server SHOULD mark all of | ||||
the courtesy locks as implicitly being renewed. | ||||
9.6.3.2. Lease Cancellation | ||||
As a result of lease expiration, leases may be cancelled, either | ||||
immediately upon expiration or subsequently, depending on the | ||||
occurrence of a conflicting lock or extension of the period of | ||||
partition beyond what the server will tolerate. | ||||
When a lease is cancelled, all locking state associated with it is | ||||
freed and use of any the associated stateids will result in | ||||
NFS4ERR_EXPIRED being returned. Similarly, use of the associated | ||||
clientid will result in NFS4ERR_EXPIRED being returned. | ||||
The client should recover from this situation by using SETCLIENTID | ||||
followed by SETCLIENTID_CONFIRM, in order to establish a new | ||||
clientid. Once a lock is obtained using this clientid, a lease will | ||||
be established. | ||||
9.6.3.3. Client's Reaction to a Freed Lock | ||||
There is no way for a client to predetermine how a given server is | ||||
going to behave during a network partition. When the partition | ||||
heals, either the client still has all of its locks, it has some of | ||||
its locks, or it has none of them. The client will be able to | ||||
examine the various error return values to determine its response. | ||||
NFS4ERR_EXPIRED: | ||||
All locks have been freed as a result of a lease cancellation | ||||
which occurred during the partition. The client should use a | ||||
SETCLIENTID to recover. | ||||
NFS4ERR_ADMIN_REVOKED: | ||||
The current lock has been revoked before, during, or after the | ||||
partition. The client SHOULD handle this error as it normally | ||||
would. | ||||
NFS4ERR_BAD_STATEID: | ||||
The current lock has been revoked/released during the partition | ||||
and the server did not reboot. Other locks MAY still be renewed. | ||||
The client need not do a SETCLIENTID and instead SHOULD probe via | ||||
a RENEW call. | ||||
NFS4ERR_RECLAIM_BAD: | ||||
The current lock has been revoked during the partition and the | ||||
server rebooted. The server might have no information on the | ||||
other locks. They may still be renewable. | ||||
NFS4ERR_NO_GRACE: | ||||
The client's locks have been revoked during the partition and the | ||||
server rebooted. None of the client's locks will be renewable. | ||||
NFS4ERR_OLD_STATEID: | ||||
The server has not rebooted. The client SHOULD handle this error | ||||
as it normally would. | ||||
9.6.3.4. Edge Conditions | ||||
When a network partition is combined with a server reboot, then both | When a network partition is combined with a server reboot, then both | |||
the server and client have responsibilities to ensure that the client | the server and client have responsibilities to ensure that the client | |||
does not reclaim a lock which it should no longer be able to access. | does not reclaim a lock which it should no longer be able to access. | |||
Briefly those are: | Briefly those are: | |||
o Client's responsibility: A client MUST NOT attempt to reclaim any | o Client's responsibility: A client MUST NOT attempt to reclaim any | |||
locks which it did not hold at the end of its most recent | locks which it did not hold at the end of its most recent | |||
successfully established client lease. | successfully established client lease. | |||
o Server's responsibility: A server MUST NOT allow a client to | o Server's responsibility: A server MUST NOT allow a client to | |||
reclaim a lock unless it knows that it could not have since | reclaim a lock unless it knows that it could not have since | |||
granted a conflicting lock. However, in deciding whether a | granted a conflicting lock. However, in deciding whether a | |||
conflicting lock could have been granted, it is permitted to | conflicting lock could have been granted, it is permitted to | |||
assume its clients are responsible, as above. | assume its clients are responsible, as above. | |||
A server may consider a client's lease "successfully established" | A server may consider a client's lease "successfully established" | |||
once it has received an open operation from that client. | once it has received an open operation from that client. | |||
The above are directed to CLAIM_PREVIOUS reclaims and not to | ||||
CLAIM_DELEGATE_PREV reclaims, which generally do not involve a server | ||||
reboot. However, when a server persistently stores delegation | ||||
information to support CLAIM_DELEGATE_PREV across a period in which | ||||
both client and server are down at the same time, similar strictures | ||||
apply. | ||||
The next sections give examples showing what can go wrong if these | The next sections give examples showing what can go wrong if these | |||
responsibilities are neglected, and provides examples of server | responsibilities are neglected, and provides examples of server | |||
implementation strategies that could meet a server's | implementation strategies that could meet a server's | |||
responsibilities. | responsibilities. | |||
9.6.3.1.1. First Server Edge Condition | 9.6.3.4.1. First Server Edge Condition | |||
The first edge condition has the following scenario: | The first edge condition has the following scenario: | |||
1. Client A acquires a lock. | 1. Client A acquires a lock. | |||
2. Client A and server experience mutual network partition, such | 2. Client A and server experience mutual network partition, such | |||
that client A is unable to renew its lease. | that client A is unable to renew its lease. | |||
3. Client A's lease expires, so server releases lock. | 3. Client A's lease expires, so server releases lock. | |||
skipping to change at page 128, line 15 | skipping to change at page 130, line 17 | |||
8. Client A issues a RENEW operation, and gets back a | 8. Client A issues a RENEW operation, and gets back a | |||
NFS4ERR_STALE_CLIENTID. | NFS4ERR_STALE_CLIENTID. | |||
9. Client A reclaims its lock within the server's grace period. | 9. Client A reclaims its lock within the server's grace period. | |||
Thus, at the final step, the server has erroneously granted client | Thus, at the final step, the server has erroneously granted client | |||
A's lock reclaim. If client B modified the object the lock was | A's lock reclaim. If client B modified the object the lock was | |||
protecting, client A will experience object corruption. | protecting, client A will experience object corruption. | |||
9.6.3.1.2. Second Server Edge Condition | 9.6.3.4.2. Second Server Edge Condition | |||
The second known edge condition follows: | The second known edge condition follows: | |||
1. Client A acquires a lock. | 1. Client A acquires a lock. | |||
2. Server reboots. | 2. Server reboots. | |||
3. Client A and server experience mutual network partition, such | 3. Client A and server experience mutual network partition, such | |||
that client A is unable to reclaim its lock within the grace | that client A is unable to reclaim its lock within the grace | |||
period. | period. | |||
skipping to change at page 128, line 48 | skipping to change at page 131, line 5 | |||
9. Client A issues a RENEW operation, and gets back a | 9. Client A issues a RENEW operation, and gets back a | |||
NFS4ERR_STALE_CLIENTID. | NFS4ERR_STALE_CLIENTID. | |||
10. Client A reclaims its lock within the server's grace period. | 10. Client A reclaims its lock within the server's grace period. | |||
As with the first edge condition, the final step of the scenario of | As with the first edge condition, the final step of the scenario of | |||
the second edge condition has the server erroneously granting client | the second edge condition has the server erroneously granting client | |||
A's lock reclaim. | A's lock reclaim. | |||
9.6.3.1.3. Handling Server Edge Conditions | 9.6.3.4.3. Handling Server Edge Conditions | |||
In both of the above examples, the client attempts reclaim of a lock | In both of the above examples, the client attempts reclaim of a lock | |||
that it held at the end of its most recent successfully established | that it held at the end of its most recent successfully established | |||
lease; thus, it has fulfilled its responsibility. | lease; thus, it has fulfilled its responsibility. | |||
The server, however, has failed, by granting a reclaim, despite | The server, however, has failed, by granting a reclaim, despite | |||
having granted a conflicting lock since the reclaimed lock was last | having granted a conflicting lock since the reclaimed lock was last | |||
held. | held. | |||
Solving these edge conditions requires that the server either assume | Solving these edge conditions requires that the server either assume | |||
skipping to change at page 129, line 45 | skipping to change at page 131, line 50 | |||
or delegation state on the server. The timestamp need not be | or delegation state on the server. The timestamp need not be | |||
updated on subsequent lock requests until the server reboots. | updated on subsequent lock requests until the server reboots. | |||
The server implementation would also record in the stable storage the | The server implementation would also record in the stable storage the | |||
timestamps from the two most recent server reboots. | timestamps from the two most recent server reboots. | |||
Assuming the above record keeping, for the first edge condition, | Assuming the above record keeping, for the first edge condition, | |||
after the server reboots, the record that client A's lease expired | after the server reboots, the record that client A's lease expired | |||
means that another client could have acquired a conflicting record | means that another client could have acquired a conflicting record | |||
lock, share reservation, or delegation. Hence the server must reject | lock, share reservation, or delegation. Hence the server must reject | |||
a reclaim from client A with the error NFS4ERR_NO_GRACE. | a reclaim from client A with the error NFS4ERR_NO_GRACE or | |||
NFS4ERR_RECLAIM_BAD. | ||||
For the second edge condition, after the server reboots for a second | For the second edge condition, after the server reboots for a second | |||
time, the record that the client had an unexpired record lock, share | time, the record that the client had an unexpired record lock, share | |||
reservation, or delegation established before the server's previous | reservation, or delegation established before the server's previous | |||
incarnation means that the server must reject a reclaim from client A | incarnation means that the server must reject a reclaim from client A | |||
with the error NFS4ERR_NO_GRACE. | with the error NFS4ERR_NO_GRACE or NFS4ERR_RECLAIM_BAD. | |||
Regardless of the level and approach to record keeping, the server | Regardless of the level and approach to record keeping, the server | |||
MUST implement one of the following strategies (which apply to | MUST implement one of the following strategies (which apply to | |||
reclaims of share reservations, byte-range locks, and delegations): | reclaims of share reservations, byte-range locks, and delegations): | |||
1. Reject all reclaims with NFS4ERR_NO_GRACE. This is super harsh, | 1. Reject all reclaims with NFS4ERR_NO_GRACE. This is super harsh, | |||
but necessary if the server does not want to record lock state in | but necessary if the server does not want to record lock state in | |||
stable storage. | stable storage. | |||
2. Record sufficient state in stable storage to meet its | 2. Record sufficient state in stable storage to meet its | |||
responsibilities. In doubt, the server should err on the side of | responsibilities. In doubt, the server should err on the side of | |||
being harsh. | being harsh. | |||
In the event that, after a server reboot, the server determines | In the event that, after a server reboot, the server determines | |||
that there is unrecoverable damage or corruption to the the | that there is unrecoverable damage or corruption to the the | |||
stable storage, then for all clients and/or locks affected, the | stable storage, then for all clients and/or locks affected, the | |||
server MUST return NFS4ERR_NO_GRACE. | server MUST return NFS4ERR_NO_GRACE. | |||
9.6.3.1.4. Client Edge Condition | 9.6.3.4.4. Client Edge Condition | |||
A third edge condition effects the client and not the server. If the | A third edge condition effects the client and not the server. If the | |||
server reboots in the middle of the client reclaiming some locks and | server reboots in the middle of the client reclaiming some locks and | |||
then a network partition is established, the client might be in the | then a network partition is established, the client might be in the | |||
situation of having reclaimed some, but not all locks. In that case, | situation of having reclaimed some, but not all locks. In that case, | |||
a conservative client would assume that the non-reclaimed locks were | a conservative client would assume that the non-reclaimed locks were | |||
revoked. | revoked. | |||
The third known edge condition follows: | The third known edge condition follows: | |||
skipping to change at page 131, line 38 | skipping to change at page 133, line 43 | |||
2. However, to do so accurately it would have to ensure that | 2. However, to do so accurately it would have to ensure that | |||
additional information about individual locks held survives reboot. | additional information about individual locks held survives reboot. | |||
Server implementations are not required to do that, so the client | Server implementations are not required to do that, so the client | |||
must not assume that the server will. | must not assume that the server will. | |||
Instead, a client MUST reclaim only those locks which it successfully | Instead, a client MUST reclaim only those locks which it successfully | |||
acquired from the previous server instance, omitting any that it | acquired from the previous server instance, omitting any that it | |||
failed to reclaim before a new reboot. Thus, in the last step above, | failed to reclaim before a new reboot. Thus, in the last step above, | |||
client A should reclaim only lock 1. | client A should reclaim only lock 1. | |||
9.6.3.1.5. Client's Handling of NFS4ERR_NO_GRACE | 9.6.3.4.5. Client's Handling of reclaim errors | |||
A mandate for the client's handling of the NFS4ERR_NO_GRACE error is | A mandate for the client's handling of the NFS4ERR_NO_GRACE and | |||
outside the scope of this specification, since the strategies for | NFS4ERR_RECLAIM_BAD errors is outside the scope of this | |||
such handling are very dependent on the client's operating | specification, since the strategies for such handling are very | |||
environment. However, one potential approach is described below. | dependent on the client's operating environment. However, one | |||
potential approach is described below. | ||||
When the client receives NFS4ERR_NO_GRACE, it could examine the | When the client's reclaim fails, it could examine the change | |||
change attribute of the objects the client is trying to reclaim state | attribute of the objects the client is trying to reclaim state for, | |||
for, and use that to determine whether to re-establish the state via | and use that to determine whether to re-establish the state via | |||
normal OPEN or LOCK requests. This is acceptable provided the | normal OPEN or LOCK requests. This is acceptable provided the | |||
client's operating environment allows it. In other words, the client | client's operating environment allows it. In other words, the client | |||
implementor is advised to document for his users the behavior. The | implementor is advised to document for his users the behavior. The | |||
client could also inform the application that its byte-range lock or | client could also inform the application that its byte-range lock or | |||
share reservations (whether they were delegated or not) have been | share reservations (whether they were delegated or not) have been | |||
lost, such as via a UNIX signal, a GUI pop-up window, etc. See | lost, such as via a UNIX signal, a GUI pop-up window, etc. See | |||
Section 10.5, for a discussion of what the client should do for | Section 10.5, for a discussion of what the client should do for | |||
dealing with unreclaimed delegations on client state. | dealing with unreclaimed delegations on client state. | |||
For further discussion of revocation of locks see Section 9.8. | For further discussion of revocation of locks see Section 9.8. | |||
9.6.3.2. Client's Reaction to a Freed Lock | ||||
There is no way for a client to predetermine how a given server is | ||||
going to behave during a network partition. When the partition | ||||
heals, either the client still has all of its locks, it has some of | ||||
its locks, or it has none of them. The client will be able to | ||||
examine the various error return values to determine its response. | ||||
NFS4ERR_EXPIRED: | ||||
All locks has been revoked during the partition. The client | ||||
should use a SETCLIENTID to recover. | ||||
NFS4ERR_ADMIN_REVOKED: | ||||
The current lock has been revoked during the partition and there | ||||
is no clue as to whether the server rebooted. | ||||
NFS4ERR_BAD_STATEID: | ||||
The current lock has been revoked during the partition and the | ||||
server did not reboot. Other locks MAY still be renewed. The | ||||
client MAY NOT want to do a SETCLIENTID and instead SHOULD probe | ||||
via a RENEW call. | ||||
NFS4ERR_NO_GRACE: | ||||
The current lock has been revoked during the partition and the | ||||
server rebooted. The server might have no information on the | ||||
other locks. They may still be renewable. | ||||
NFS4ERR_OLD_STATEID: | ||||
The server has not rebooted. The client SHOULD handle this error | ||||
as it normally would. | ||||
9.7. Recovery from a Lock Request Timeout or Abort | 9.7. Recovery from a Lock Request Timeout or Abort | |||
In the event a lock request times out, a client may decide to not | In the event a lock request times out, a client may decide to not | |||
retry the request. The client may also abort the request when the | retry the request. The client may also abort the request when the | |||
process for which it was issued is terminated (e.g., in UNIX due to a | process for which it was issued is terminated (e.g., in UNIX due to a | |||
signal). It is possible though that the server received the request | signal). It is possible though that the server received the request | |||
and acted upon it. This would change the state on the server without | and acted upon it. This would change the state on the server without | |||
the client being aware of the change. It is paramount that the | the client being aware of the change. It is paramount that the | |||
client re-synchronize state with server before it attempts any other | client re-synchronize state with server before it attempts any other | |||
operation that takes a seqid and/or a stateid with the same state- | operation that takes a seqid and/or a stateid with the same state- | |||
skipping to change at page 144, line 49 | skipping to change at page 146, line 15 | |||
10.2.1. Delegation Recovery | 10.2.1. Delegation Recovery | |||
There are three situations that delegation recovery must deal with: | There are three situations that delegation recovery must deal with: | |||
o Client reboot or restart | o Client reboot or restart | |||
o Server reboot or restart | o Server reboot or restart | |||
o Network partition (full or callback-only) | o Network partition (full or callback-only) | |||
In the event the client reboots or restarts, the failure to renew | In the event the client reboots or restarts, the confirmation of a | |||
leases will result in the revocation of byte-range locks and share | SETCLIENTID done with an nfs_client_id4 with a new verifier4 value | |||
will result in the release of byte-range locks and share | ||||
reservations. Delegations, however, may be treated a bit | reservations. Delegations, however, may be treated a bit | |||
differently. | differently. | |||
There will be situations in which delegations will need to be | There will be situations in which delegations will need to be | |||
reestablished after a client reboots or restarts. The reason for | reestablished after a client reboots or restarts. The reason for | |||
this is the client may have file data stored locally and this data | this is the client may have file data stored locally and this data | |||
was associated with the previously held delegations. The client will | was associated with the previously held delegations. The client will | |||
need to reestablish the appropriate file state on the server. | need to reestablish the appropriate file state on the server. | |||
To allow for this type of client recovery, the server MAY extend the | To allow for this type of client recovery, the server MAY allow | |||
period for delegation recovery beyond the typical lease expiration | delegations to be retained after other sort of locks are released. | |||
period. This implies that requests from other clients that conflict | This implies that requests from other clients that conflict with | |||
with these delegations will need to wait. Because the normal recall | these delegations will need to wait. Because the normal recall | |||
process may require significant time for the client to flush changed | process may require significant time for the client to flush changed | |||
state to the server, other clients need be prepared for delays that | state to the server, other clients need to be prepared for delays | |||
occur because of a conflicting delegation. This longer interval | that occur because of a conflicting delegation. In order to give | |||
would increase the window for clients to reboot and consult stable | clients a chance to get through the reboot process during which | |||
storage so that the delegations can be reclaimed. For open | leases will not be renewed, the server MAY extend the period for | |||
delegations, such delegations are reclaimed using OPEN with a claim | delegation recovery beyond the typical lease expiration period. For | |||
type of CLAIM_DELEGATE_PREV. (See Section 10.5 and Section 15.18 for | open delegations, such delegations that are not released are | |||
discussion of open delegation and the details of OPEN respectively). | reclaimed using OPEN with a claim type of CLAIM_DELEGATE_PREV. (See | |||
Section 10.5 and Section 15.18 for discussion of open delegation and | ||||
the details of OPEN respectively). | ||||
A server MAY support a claim type of CLAIM_DELEGATE_PREV, but if it | A server MAY support a claim type of CLAIM_DELEGATE_PREV, but if it | |||
does, it MUST NOT remove delegations upon SETCLIENTID_CONFIRM, and | does, it MUST NOT remove delegations upon SETCLIENTID_CONFIRM and | |||
instead MUST, for a period of time no less than that of the value of | instead MUST make them available for client reclaim using | |||
the lease_time attribute, maintain the client's delegations to allow | CLAIM_DELEGATE_PREV. The server MAY NOT remove the delegations until | |||
time for the client to issue CLAIM_DELEGATE_PREV requests. The | either the client does a DELEGPURGE, or one lease period has elapsed | |||
server that supports CLAIM_DELEGATE_PREV MUST support the DELEGPURGE | from the time the later of the SETCLIENTID_CONFIRM or the last | |||
successful CLAIM_DELEGATE_PREV reclaim. | ||||
Note that the requirement stated above is not meant to imply that | ||||
when the client is no longer obliged, as required above, to retain | ||||
delegation information, that it should necessarily dispose of it. | ||||
Some specific cases are: | ||||
o When the period is terminated by the occurrence of DELEGPURGE, | ||||
deletion of unreclaimed delegations is appropriate and desirable. | ||||
o When the period is terminated by a lease period elapsing without a | ||||
successful CLAIM_DELEGATE_PREV reclaim, and that situation appears | ||||
to be the result of a network partition (i.e., lease expiration | ||||
has occurred), a server's lease expiration approach, possibly | ||||
including the use of courtesy locks would normally provide for the | ||||
retention of unreclaimed delegations. Even in the event that | ||||
lease cancellation occurs, such delegation should be reclaimed | ||||
using CLAIM_DELEGATE_PREV as part of network partition recovery. | ||||
o When the period of non-communicating is followed by a client | ||||
reboot, unreclaimed delegations, should also be reclaimable by use | ||||
of CLAIM_DELEGATE_PREV as part of client reboot recovery. | ||||
o When the period is terminated by a lease period elapsing without a | ||||
successful CLAIM_DELEGATE_PREV reclaim, and lease renewal is | ||||
occurring, the server may well conclude that unreclaimed | ||||
delegations have been abandoned, and consider the situation as one | ||||
in which an implied DELEGPURGE should be assumed. | ||||
A server that supports a claim type of CLAIM_DELEGATE_PREV MUST | ||||
support the DELEGPURGE operation, and similarly a server that | ||||
supports DELEGPURGE MUST support CLAIM_DELEGATE_PREV. A server which | ||||
does not support CLAIM_DELEGATE_PREV MUST return NFS4ERR_NOTSUPP if | ||||
the client attempts to use that feature or performs a DELEGPURGE | ||||
operation. | operation. | |||
Support for a claim type of CLAIM_DELEGATE_PREV, is often referred to | ||||
as providing for "client-persistent delegations" in that they allow | ||||
use of client persistent storage on the client to store data written | ||||
by the client, even across a client restart. It should be noted | ||||
that, with the optional exception noted below, this feature requires | ||||
persistent storage to be used on the client and does not add to | ||||
persistent storage requirements on the server. | ||||
One good way to think about client-persistent delegations is that for | ||||
the most part, they function like "courtesy locks", with a special | ||||
semantic adjustments to allow them to be retained across a client | ||||
restart, which cause all other sorts of locks to be freed. Such | ||||
locks are generally not retained across a server restart. The one | ||||
exception is the case of simultaneous failure of the client and | ||||
server and is discussed below. | ||||
When the server indicates support of CLAIM_DELEGATE_PREV (implicitly) | ||||
by returning NFS_OK to DELEGPURGE, a client with a write delegation, | ||||
can use write-back caching for data to be written to the server, | ||||
deferring the write-back, until such time as the delegation is | ||||
recalled, possibly after intervening client restarts. Similarly, | ||||
when the server indicates support of CLAIM_DELEGATE_PREV, a client | ||||
with a read delegation and an open-for-write subordinate to that | ||||
delegation, may be sure of the integrity of its persistently cached | ||||
copy of the file after a client restart without specific verification | ||||
of the change attribute. | ||||
When the server reboots or restarts, delegations are reclaimed (using | When the server reboots or restarts, delegations are reclaimed (using | |||
the OPEN operation with CLAIM_PREVIOUS) in a similar fashion to byte- | the OPEN operation with CLAIM_PREVIOUS) in a similar fashion to byte- | |||
range locks and share reservations. However, there is a slight | range locks and share reservations. However, there is a slight | |||
semantic difference. In the normal case if the server decides that a | semantic difference. In the normal case, if the server decides that | |||
delegation should not be granted, it performs the requested action | a delegation should not be granted, it performs the requested action | |||
(e.g., OPEN) without granting any delegation. For reclaim, the | (e.g., OPEN) without granting any delegation. For reclaim, the | |||
server grants the delegation but a special designation is applied so | server grants the delegation but a special designation is applied so | |||
that the client treats the delegation as having been granted but | that the client treats the delegation as having been granted but | |||
recalled by the server. Because of this, the client has the duty to | recalled by the server. Because of this, the client has the duty to | |||
write all modified state to the server and then return the | write all modified state to the server and then return the | |||
delegation. This process of handling delegation reclaim reconciles | delegation. This process of handling delegation reclaim reconciles | |||
three principles of the NFSv4 protocol: | three principles of the NFSv4 protocol: | |||
o Upon reclaim, a client reporting resources assigned to it by an | o Upon reclaim, a client reporting resources assigned to it by an | |||
earlier server instance must be granted those resources. | earlier server instance must be granted those resources. | |||
skipping to change at page 146, line 14 | skipping to change at page 148, line 43 | |||
o The use of callbacks is not to be depended upon until the client | o The use of callbacks is not to be depended upon until the client | |||
has proven its ability to receive them. | has proven its ability to receive them. | |||
When a client has more than a single open associated with a | When a client has more than a single open associated with a | |||
delegation, state for those additional opens can be established using | delegation, state for those additional opens can be established using | |||
OPEN operations of type CLAIM_DELEGATE_CUR. When these are used to | OPEN operations of type CLAIM_DELEGATE_CUR. When these are used to | |||
establish opens associated with reclaimed delegations, the server | establish opens associated with reclaimed delegations, the server | |||
MUST allow them when made within the grace period. | MUST allow them when made within the grace period. | |||
Situations in which there us a series of client and server restarts | ||||
where there is no restart of both at the same time, are dealt with | ||||
via a combination of CLAIM_DELEGATE_PREV and CLAIM_PREVIOUS reclaim | ||||
cycles. Persistent storage is needed only on the client. For each | ||||
server failure, a CLAIM_PREVIOUS reclaim cycle is done, while for | ||||
each client restart, a CLAIM_DELEGATE_PREV reclaim cycle is done. | ||||
To deal with the possibility of simultaneous failure of client and | ||||
server (e.g., a data center power outage), the server MAY | ||||
persistently store delegation information so that it can respond to a | ||||
CLAIM_DELEGATE_PREV reclaim request which it receives from a | ||||
restarting client. This is the one case in which persistent | ||||
delegation state can be retained across a server restart. A server | ||||
is not required to store this information, but if it does do so, it | ||||
should do so for write delegations and for read delegations, during | ||||
the pendency of which (across multiple client and/or server | ||||
instances), some open-for-write was done as part of delegation. When | ||||
the space to persistently record such information is limited, the | ||||
server should recall delegations in this class in preference to | ||||
keeping them active without persistent storage recording. | ||||
When a network partition occurs, delegations are subject to freeing | When a network partition occurs, delegations are subject to freeing | |||
by the server when the lease renewal period expires. This is similar | by the server when the lease renewal period expires. This is similar | |||
to the behavior for locks and share reservations. For delegations, | to the behavior for locks and share reservations, and, as for locks | |||
however, the server may extend the period in which conflicting | and share reservations it may be modified by support for "courtesy | |||
requests are held off. Eventually the occurrence of a conflicting | locks" in which locks are not freed in the absence of a conflicting | |||
request from another client will cause revocation of the delegation. | lock request. Whereas, for locks and share reservations, freeing of | |||
locks will occur immediately upon the appearance of a conflicting | ||||
request, for delegations, the server may institute period during | ||||
which conflicting requests are held off. Eventually the occurrence | ||||
of a conflicting request from another client will cause revocation of | ||||
the delegation. | ||||
A loss of the callback path (e.g., by later network configuration | A loss of the callback path (e.g., by later network configuration | |||
change) will have the same effect. A recall request will fail and | change) will have a similar effect in that it can also result in | |||
revocation of the delegation will result. | revocation of a delegation A recall request will fail and revocation | |||
of the delegation will result. | ||||
A client normally finds out about revocation of a delegation when it | A client normally finds out about revocation of a delegation when it | |||
uses a stateid associated with a delegation and receives the error | uses a stateid associated with a delegation and receives one of the | |||
NFS4ERR_EXPIRED. It also may find out about delegation revocation | errors NFS4ERR_EXPIRED, NFS4ERR_BAD_STATEID, or NFS4ERR_ADMIN_REVOKED | |||
after a client reboot when it attempts to reclaim a delegation and | (NFS4ERR_EXPIRED indicates that all lock state associated with the | |||
receives that same error. Note that in the case of a revoked | client has been lost). It also may find out about delegation | |||
OPEN_DELEGATE_WRITE delegation, there are issues because data may | revocation after a client reboot when it attempts to reclaim a | |||
have been modified by the client whose delegation is revoked and | delegation and receives NFS4ERR_EXPIRED. Note that in the case of a | |||
revoked OPEN_DELEGATE_WRITE delegation, there are issues because data | ||||
may have been modified by the client whose delegation is revoked and | ||||
separately by other clients. See Section 10.5.1 for a discussion of | separately by other clients. See Section 10.5.1 for a discussion of | |||
such issues. Note also that when delegations are revoked, | such issues. Note also that when delegations are revoked, | |||
information about the revoked delegation will be written by the | information about the revoked delegation will be written by the | |||
server to stable storage (as described in Section 9.6). This is done | server to stable storage (as described in Section 9.6). This is done | |||
to deal with the case in which a server reboots after revoking a | to deal with the case in which a server reboots after revoking a | |||
delegation but before the client holding the revoked delegation is | delegation but before the client holding the revoked delegation is | |||
notified about the revocation. | notified about the revocation. | |||
Note that when there is a loss of a delegation, due to a network | ||||
partition in which all locks associated with the lease are lost, the | ||||
client will also receive the error NFS4ERR_EXPIRED. This case can be | ||||
distinguished from other situations in which delegations are revoked | ||||
by seeing that the associated clientid becomes invalid so that | ||||
NFS4ERR_STALE_CLIENTID is returned when it is used. | ||||
When NFS4ERR_EXPIRED Is returned, the server MAY retain information | ||||
about the delegations held by the client, deleting those that are | ||||
invalidated by a conflicting request. Retaining such information | ||||
will allow the client to recover all non-invalidated delegations | ||||
using the claim type CLAIM_DELEGATE_PREV, once the | ||||
SETCLIENTID_CONFIRM is done to recover. Attempted recovery of a | ||||
delegation that the client has no record of, typically because they | ||||
were invalidated by conflicting requests, will get the error | ||||
NFS4ERR_BAD_RECLAIM. Once a reclaim is attempted for all delegations | ||||
that the client held, it SHOULD do a DELEGPURGE to allow any | ||||
remaining server delegation information to be freed. | ||||
10.3. Data Caching | 10.3. Data Caching | |||
When applications share access to a set of files, they need to be | When applications share access to a set of files, they need to be | |||
implemented so as to take account of the possibility of conflicting | implemented so as to take account of the possibility of conflicting | |||
access by another application. This is true whether the applications | access by another application. This is true whether the applications | |||
in question execute on different clients or reside on the same | in question execute on different clients or reside on the same | |||
client. | client. | |||
Share reservations and byte-range locks are the facilities the NFS | Share reservations and byte-range locks are the facilities the NFS | |||
version 4 protocol provides to allow applications to coordinate | version 4 protocol provides to allow applications to coordinate | |||
skipping to change at page 202, line 22 | skipping to change at page 206, line 8 | |||
These errors indicate problems with the stateid (or one of the | These errors indicate problems with the stateid (or one of the | |||
stateids) passed to a given operation. This includes situations in | stateids) passed to a given operation. This includes situations in | |||
which the stateid is invalid as well as situations in which the | which the stateid is invalid as well as situations in which the | |||
stateid is valid but designates revoked locking state. Depending on | stateid is valid but designates revoked locking state. Depending on | |||
the operation, the stateid when valid may designate opens, byte-range | the operation, the stateid when valid may designate opens, byte-range | |||
locks, or file delegations. | locks, or file delegations. | |||
13.1.5.1. NFS4ERR_ADMIN_REVOKED (Error Code 10047) | 13.1.5.1. NFS4ERR_ADMIN_REVOKED (Error Code 10047) | |||
A stateid designates locking state of any type that has been revoked | A stateid designates locking state of any type that has been revoked | |||
due to administrative interaction, possibly while the lease is valid. | due to administrative interaction, possibly while the lease is valid, | |||
or because a delegation was revoked because of failure to return it, | ||||
while the lease was valid. | ||||
13.1.5.2. NFS4ERR_BAD_STATEID (Error Code 10026) | 13.1.5.2. NFS4ERR_BAD_STATEID (Error Code 10026) | |||
A stateid generated by the current server instance, but which does | A stateid generated by the current server instance was used which | |||
not designate any locking state (either current or superseded) for a | either: | |||
current (state-owner, file) pair, was used. | ||||
o Does not designate any locking state (either current or | ||||
superseded) for a current (state-owner, file) pair. | ||||
o Designates locking state that was freed after lease expiration but | ||||
without any lease cancelation, as may happen in the handling of | ||||
"courtesy locks". | ||||
13.1.5.3. NFS4ERR_EXPIRED (Error Code 10011) | 13.1.5.3. NFS4ERR_EXPIRED (Error Code 10011) | |||
A stateid designates locking state of any type that has been revoked | A stateid or clientid designates locking state of any type that has | |||
due to expiration of the client's lease, either immediately upon | been revoked or released due to cancellation of the client's lease, | |||
lease expiration, or following a later request for a conflicting | either immediately upon lease expiration, or following a later | |||
lock. | request for a conflicting lock. | |||
13.1.5.4. NFS4ERR_LEASE_MOVED (Error Code 10031) | 13.1.5.4. NFS4ERR_LEASE_MOVED (Error Code 10031) | |||
A lease being renewed is associated with a file system that has been | A lease being renewed is associated with a file system that has been | |||
migrated to a new server. | migrated to a new server. | |||
13.1.5.5. NFS4ERR_OLD_STATEID (Error Code 10024) | 13.1.5.5. NFS4ERR_OLD_STATEID (Error Code 10024) | |||
A stateid is provided with a seqid value that is not the most | A stateid is provided with a seqid value that is not the most | |||
current. | current. | |||
skipping to change at page 205, line 47 | skipping to change at page 209, line 40 | |||
restart. | restart. | |||
13.1.9.1. NFS4ERR_GRACE (Error Code 10013) | 13.1.9.1. NFS4ERR_GRACE (Error Code 10013) | |||
The server is in its recovery or grace period which should at least | The server is in its recovery or grace period which should at least | |||
match the lease period of the server. A locking request other than a | match the lease period of the server. A locking request other than a | |||
reclaim could not be granted during that period. | reclaim could not be granted during that period. | |||
13.1.9.2. NFS4ERR_NO_GRACE (Error Code 10033) | 13.1.9.2. NFS4ERR_NO_GRACE (Error Code 10033) | |||
A reclaim of client state was attempted in circumstances in which the | The server cannot guarantee that it has not granted state to another | |||
server cannot guarantee that conflicting state has not been provided | client which may conflict with this client's state. No further | |||
to another client. As a result, the server cannot guarantee that | reclaims from this client will succeed. | |||
conflicting state has not been provided to another client. | ||||
13.1.9.3. NFS4ERR_RECLAIM_BAD (Error Code 10034) | 13.1.9.3. NFS4ERR_RECLAIM_BAD (Error Code 10034) | |||
A reclaim attempted by the client does not match the server's state | The server cannot guarantee that it has not granted state to another | |||
consistency checks and has been rejected therefore as invalid. | client which may conflict with the requested state. However, this | |||
applies only to the state requested in this call; further reclaims | ||||
may succeed. | ||||
Unlike NFS4ERR_RECLAIM_CONFLICT, this can occur between correctly | ||||
functioning clients and servers: the "edge condition" scenarios | ||||
described in Section 9.6.3.1 leave only the server knowing whether | ||||
the client's locks are still valid, and NFS4ERR_RECLAIM_BAD is the | ||||
server's way of informing the client that they are not. | ||||
13.1.9.4. NFS4ERR_RECLAIM_CONFLICT (Error Code 10035) | 13.1.9.4. NFS4ERR_RECLAIM_CONFLICT (Error Code 10035) | |||
The reclaim attempted by the client has encountered a conflict and | The reclaim attempted by the client conflicts with a lock already | |||
cannot be satisfied. Potentially indicates a misbehaving client, | held by another client. Unlike NFS4ERR_RECLAIM_BAD, this can only | |||
although not necessarily the one receiving the error. The | occur if one of the clients misbehaved. | |||
misbehavior might be on the part of the client that established the | ||||
lock with which this client conflicted. | ||||
13.1.10. Client Management Errors | 13.1.10. Client Management Errors | |||
This sections deals with errors associated with requests used to | This sections deals with errors associated with requests used to | |||
create and manage client IDs. | create and manage client IDs. | |||
13.1.10.1. NFS4ERR_CLID_INUSE (Error Code 10017) | 13.1.10.1. NFS4ERR_CLID_INUSE (Error Code 10017) | |||
The SETCLIENTID operation has found that a client id is already in | The SETCLIENTID operation has found that a client id is already in | |||
use by another client. | use by another client. | |||
skipping to change at page 235, line 18 | skipping to change at page 239, line 18 | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | }; | |||
15.7.4. DESCRIPTION | 15.7.4. DESCRIPTION | |||
Purges all of the delegations awaiting recovery for a given client. | Purges all of the delegations awaiting recovery for a given client. | |||
This is useful for clients which do not commit delegation information | This is useful for clients which do not commit delegation information | |||
to stable storage to indicate that conflicting requests need not be | to stable storage to indicate that conflicting requests need not be | |||
delayed by the server awaiting recovery of delegation information. | delayed by the server awaiting recovery of delegation information. | |||
This operation should be used by clients that record delegation | This operation in provided to support clients that record delegation | |||
information on stable storage on the client. In this case, | information on stable storage on the client. In this case, | |||
DELEGPURGE should be issued immediately after doing delegation | DELEGPURGE should be issued immediately after doing delegation | |||
recovery on all delegations known to the client. Doing so will | recovery (using CLAIM_DELEGATE_PREV) on all delegations known to the | |||
notify the server that no additional delegations for the client will | client. Doing so will notify the server that no additional | |||
be recovered allowing it to free resources, and avoid delaying other | delegations for the client will be recovered allowing it to free | |||
clients who make requests that conflict with the unrecovered | resources, and avoid delaying other clients who make requests that | |||
delegations. The set of delegations known to the server and the | conflict with the unrecovered delegations. All client SHOULD use | |||
client may be different. The reason for this is that a client may | DELEGPURGE as part of recovery once it is known that no further | |||
fail after making a request which resulted in delegation but before | CLAIM_DELEGATE_PREV recovery will be done. This includes clients | |||
it received the results and committed them to the client's stable | that do not record delegation information on stable storage, who | |||
storage. | would then do a DELEGPURGE immediately after SETCLIENTID_CONFIRM. | |||
The server MAY support DELEGPURGE, but if it does not, it MUST NOT | The set of delegations known to the server and the client may be | |||
support CLAIM_DELEGATE_PREV. | different. The reasons for this include: | |||
o A client may fail after making a request which resulted in | ||||
delegation but before it received the results and committed them | ||||
to the client's stable storage. | ||||
o A client may fail after deleting its indication that a delegation | ||||
exists but before the delegation return is fully processed by the | ||||
server. | ||||
o In the case in which the server and the client restart, the server | ||||
may have limited persistent recording of delegation to a subset of | ||||
those in existence. | ||||
o A client may have only persistently recorded information about a | ||||
subset of delegations. | ||||
The server MAY support DELEGPURGE, but its support or non-support | ||||
should match that of CLAIM_DELEGATE_PREV: | ||||
o A server may support both DELEGPURGE and CLAIM_DELEGATE_PREV. | ||||
o A server may support neither DELEGPURGE nor CLAIM_DELEGATE_PREV. | ||||
This fact allows a client starting up to determine if the server is | ||||
prepared to support persistent storage of delegation information and | ||||
thus whether it may use write-back caching to local persistent | ||||
storage, relying on CLAIM_DELEGATE_PREV recovery to allow such | ||||
changed data to be flushed safely to the server in the event of | ||||
client restart. | ||||
15.8. Operation 8: DELEGRETURN - Return Delegation | 15.8. Operation 8: DELEGRETURN - Return Delegation | |||
15.8.1. SYNOPSIS | 15.8.1. SYNOPSIS | |||
(cfh), stateid -> | (cfh), stateid -> | |||
15.8.2. ARGUMENT | 15.8.2. ARGUMENT | |||
struct DELEGRETURN4args { | struct DELEGRETURN4args { | |||
skipping to change at page 244, line 30 | skipping to change at page 249, line 30 | |||
the server, this establishes an initial sequence value for the new | the server, this establishes an initial sequence value for the new | |||
lock-owner. | lock-owner. | |||
o In the case in which the state has been created and the boolean is | o In the case in which the state has been created and the boolean is | |||
false, the only part of the argument other than lock_seqid is just | false, the only part of the argument other than lock_seqid is just | |||
a stateid representing the set of locks associated with that open | a stateid representing the set of locks associated with that open | |||
file and lock-owner. | file and lock-owner. | |||
o In the case in which the state has been created and the boolean is | o In the case in which the state has been created and the boolean is | |||
true, the server rejects the request with the error | true, the server rejects the request with the error | |||
NFS4ERR_BADSEQ. The only exception is where there is a | NFS4ERR_BAD_SEQID. The only exception is where there is a | |||
retransmission of a previous request in which the boolean was | retransmission of a previous request in which the boolean was | |||
true. In this case, the lock_seqid will match the original | true. In this case, the lock_seqid will match the original | |||
request and the response will reflect the final case, below. | request and the response will reflect the final case, below. | |||
o In the case where no byte-range locking state has been established | o In the case where no byte-range locking state has been established | |||
and the boolean is true, the argument contains an | and the boolean is true, the argument contains an | |||
open_to_lock_owner structure which specifies the stateid of the | open_to_lock_owner structure which specifies the stateid of the | |||
open file and the lock-owner to be used for the lock. Note that | open file and the lock-owner to be used for the lock. Note that | |||
although the open-owner is not given explicitly, the open_seqid | although the open-owner is not given explicitly, the open_seqid | |||
associated with it is used to check for open-owner sequencing | associated with it is used to check for open-owner sequencing | |||
skipping to change at page 255, line 17 | skipping to change at page 260, line 17 | |||
}; | }; | |||
union OPEN4res switch (nfsstat4 status) { | union OPEN4res switch (nfsstat4 status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
/* CURRENT_FH: opened file */ | /* CURRENT_FH: opened file */ | |||
OPEN4resok resok4; | OPEN4resok resok4; | |||
default: | default: | |||
void; | void; | |||
}; | }; | |||
15.18.4. WARNING TO CLIENT IMPLEMENTORS | 15.18.4. Warning to Client Implementors | |||
OPEN resembles LOOKUP in that it generates a filehandle for the | OPEN resembles LOOKUP in that it generates a filehandle for the | |||
client to use. Unlike LOOKUP though, OPEN creates server state on | client to use. Unlike LOOKUP though, OPEN creates server state on | |||
the filehandle. In normal circumstances, the client can only release | the filehandle. In normal circumstances, the client can only release | |||
this state with a CLOSE operation. CLOSE uses the current filehandle | this state with a CLOSE operation. CLOSE uses the current filehandle | |||
to determine which file to close. Therefore the client MUST follow | to determine which file to close. Therefore, the client MUST follow | |||
every OPEN operation with a GETFH operation in the same COMPOUND | every OPEN operation with a GETFH operation in the same COMPOUND | |||
procedure. This will supply the client with the filehandle such that | procedure. This will supply the client with the filehandle such that | |||
CLOSE can be used appropriately. | CLOSE can be used appropriately. | |||
Simply waiting for the lease on the file to expire is insufficient | Simply waiting for the lease on the file to expire is insufficient | |||
because the server may maintain the state indefinitely as long as | because the server may maintain the state indefinitely as long as | |||
another client does not attempt to make a conflicting access to the | another client does not attempt to make a conflicting access to the | |||
same file. | same file. | |||
15.18.5. DESCRIPTION | 15.18.5. DESCRIPTION | |||
skipping to change at page 257, line 24 | skipping to change at page 262, line 24 | |||
CLAIM_PREVIOUS: The client is claiming basic OPEN state for a file | CLAIM_PREVIOUS: The client is claiming basic OPEN state for a file | |||
that was held previous to a server reboot. Generally used when a | that was held previous to a server reboot. Generally used when a | |||
server is returning persistent filehandles; the client may not | server is returning persistent filehandles; the client may not | |||
have the file name to reclaim the OPEN. | have the file name to reclaim the OPEN. | |||
CLAIM_DELEGATE_CUR: The client is claiming a delegation for OPEN as | CLAIM_DELEGATE_CUR: The client is claiming a delegation for OPEN as | |||
granted by the server. Generally this is done as part of | granted by the server. Generally this is done as part of | |||
recalling a delegation. | recalling a delegation. | |||
CLAIM_DELEGATE_PREV: The client is claiming a delegation granted to | CLAIM_DELEGATE_PREV: The client is claiming a delegation granted to | |||
a previous client instance; used after the client reboots. The | a previous client instance. This claim type is for use after a | |||
server MAY support CLAIM_DELEGATE_PREV. If it does support | SETCLIENTID_CONFIRM and before the corresponding DELEGPURGE in two | |||
CLAIM_DELEGATE_PREV, SETCLIENTID_CONFIRM MUST NOT remove the | situations: after a client reboot and after a lease expiration | |||
client's delegation state, and the server MUST support the | that resulted in loss of all lock state. The server MAY support | |||
DELEGPURGE operation. | CLAIM_DELEGATE_PREV. If it does support CLAIM_DELEGATE_PREV, | |||
SETCLIENTID_CONFIRM MUST NOT remove the client's delegation state, | ||||
and the server MUST support the DELEGPURGE operation. | ||||
The following errors apply to use of the CLAIM_DELEGATE_PREV claim | ||||
type: | ||||
o NFS4ERR_NOTSUPP is returned if the server does not support this | ||||
claim type. | ||||
o NFS4ERR_INVAL is returned if the reclaim is done at an | ||||
inappropriate time, e.g., after DELEGPURGE has been done. | ||||
o NFS4ERR_BAD_RECLAIM is returned if the other error conditions do | ||||
not apply and the server has no record of the delegation whose | ||||
reclaim is being attempted. | ||||
For OPEN requests whose claim type is other than CLAIM_PREVIOUS | For OPEN requests whose claim type is other than CLAIM_PREVIOUS | |||
(i.e., requests other than those devoted to reclaiming opens after a | (i.e., requests other than those devoted to reclaiming opens after a | |||
server reboot) that reach the server during its grace or lease | server reboot) that reach the server during its grace or lease | |||
expiration period, the server returns an error of NFS4ERR_GRACE. | expiration period, the server returns an error of NFS4ERR_GRACE. | |||
For any OPEN request, the server may return an open delegation, which | For any OPEN request, the server may return an open delegation, which | |||
allows further opens and closes to be handled locally on the client | allows further opens and closes to be handled locally on the client | |||
as described in Section 10.4. Note that delegation is up to the | as described in Section 10.4. Note that delegation is up to the | |||
server to decide. The client should never assume that delegation | server to decide. The client should never assume that delegation | |||
skipping to change at page 261, line 5 | skipping to change at page 266, line 18 | |||
If a COMPOUND contains an OPEN which establishes a | If a COMPOUND contains an OPEN which establishes a | |||
OPEN_DELEGATE_WRITE delegation, then a subsequent GETATTR inside that | OPEN_DELEGATE_WRITE delegation, then a subsequent GETATTR inside that | |||
COMPOUND SHOULD not result in a CB_GETATTR to the client. The server | COMPOUND SHOULD not result in a CB_GETATTR to the client. The server | |||
SHOULD understand the GETATTR to be for the same client ID and avoid | SHOULD understand the GETATTR to be for the same client ID and avoid | |||
querying the client, which will not be able to respond. This | querying the client, which will not be able to respond. This | |||
sequence of OPEN, GETATTR SHOULD be understood as an atomic retrieval | sequence of OPEN, GETATTR SHOULD be understood as an atomic retrieval | |||
of the initial size and change attribute. Further, the client SHOULD | of the initial size and change attribute. Further, the client SHOULD | |||
NOT construct a COMPOUND which mixes operations for different client | NOT construct a COMPOUND which mixes operations for different client | |||
IDs. | IDs. | |||
15.18.7. Warning to Client Implementors | ||||
OPEN resembles LOOKUP in that it generates a filehandle for the | ||||
client to use. Unlike LOOKUP though, OPEN creates server state on | ||||
the filehandle. In normal circumstances, the client can only release | ||||
this state with a CLOSE operation. CLOSE uses the current filehandle | ||||
to determine which file to close. Therefore, the client MUST follow | ||||
every OPEN operation with a GETFH operation in the same COMPOUND | ||||
procedure. This will supply the client with the filehandle such that | ||||
CLOSE can be used appropriately. | ||||
Simply waiting for the lease on the file to expire is insufficient | ||||
because the server may maintain the state indefinitely as long as | ||||
another client does not attempt to make a conflicting access to the | ||||
same file. | ||||
15.19. Operation 19: OPENATTR - Open Named Attribute Directory | 15.19. Operation 19: OPENATTR - Open Named Attribute Directory | |||
15.19.1. SYNOPSIS | 15.19.1. SYNOPSIS | |||
(cfh) createdir -> (cfh) | (cfh) createdir -> (cfh) | |||
15.19.2. ARGUMENT | 15.19.2. ARGUMENT | |||
struct OPENATTR4args { | struct OPENATTR4args { | |||
/* CURRENT_FH: object */ | /* CURRENT_FH: object */ | |||
skipping to change at page 292, line 26 | skipping to change at page 297, line 26 | |||
delegation) state for x. | delegation) state for x. | |||
The server generates the clientid and setclientid_confirm values and | The server generates the clientid and setclientid_confirm values and | |||
must take care to ensure that these values are extremely unlikely to | must take care to ensure that these values are extremely unlikely to | |||
ever be regenerated. | ever be regenerated. | |||
15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID | 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID | |||
15.36.1. SYNOPSIS | 15.36.1. SYNOPSIS | |||
clientid, verifier -> - | clientid, setclientid_confirm -> - | |||
15.36.2. ARGUMENT | 15.36.2. ARGUMENT | |||
struct SETCLIENTID_CONFIRM4args { | struct SETCLIENTID_CONFIRM4args { | |||
clientid4 clientid; | clientid4 clientid; | |||
verifier4 setclientid_confirm; | verifier4 setclientid_confirm; | |||
}; | }; | |||
15.36.3. RESULT | 15.36.3. RESULT | |||
End of changes. 60 change blocks. | ||||
319 lines changed or deleted | 532 lines changed or added | |||
This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |