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/