Found wdiff, but it reported no recognisable version. Falling back to builtin diff colouring... Diff: draft-pre-ch-11.txt - draft-ietf-nfsv4-minorversion1-22.txt
 draft-pre-ch-11.txt   draft-ietf-nfsv4-minorversion1-22.txt 
NFSv4 S. Shepler NFSv4 S. Shepler
Internet-Draft M. Eisler Internet-Draft M. Eisler
Intended status: Standards Track D. Noveck Intended status: Standards Track D. Noveck
Expires: September 22, 2008 Editors Expires: September 23, 2008 Editors
March 21, 2008 March 22, 2008
NFS Version 4 Minor Version 1 NFS Version 4 Minor Version 1
draft-ietf-nfsv4-minorversion1-22.txt draft-ietf-nfsv4-minorversion1-22.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
skipping to change at page 1, line 35 skipping to change at page 1, line 35
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."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 22, 2008. This Internet-Draft will expire on September 23, 2008.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2008). Copyright (C) The IETF Trust (2008).
Abstract Abstract
This Internet-Draft describes NFS version 4 minor version one, This Internet-Draft describes NFS version 4 minor version one,
including features retained from the base protocol and protocol including features retained from the base protocol and protocol
extensions made subsequently. Major extensions introduced in NFS extensions made subsequently. Major extensions introduced in NFS
skipping to change at page 6, line 17 skipping to change at page 6, line 17
11.7.7. Lock State and File System Transitions . . . . . . . 232 11.7.7. Lock State and File System Transitions . . . . . . . 232
11.7.8. Write Verifiers and File System Transitions . . . . 236 11.7.8. Write Verifiers and File System Transitions . . . . 236
11.7.9. Readdir Cookies and Verifiers and File System 11.7.9. Readdir Cookies and Verifiers and File System
Transitions . . . . . . . . . . . . . . . . . . . . 236 Transitions . . . . . . . . . . . . . . . . . . . . 236
11.7.10. File System Data and File System Transitions . . . . 236 11.7.10. File System Data and File System Transitions . . . . 236
11.8. Effecting File System Referrals . . . . . . . . . . . . 238 11.8. Effecting File System Referrals . . . . . . . . . . . . 238
11.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 238 11.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 238
11.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 242 11.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 242
11.9. The Attribute fs_locations . . . . . . . . . . . . . . . 244 11.9. The Attribute fs_locations . . . . . . . . . . . . . . . 244
11.10. The Attribute fs_locations_info . . . . . . . . . . . . 247 11.10. The Attribute fs_locations_info . . . . . . . . . . . . 247
11.10.1. The fs_locations_server4 Structure . . . . . . . . . 250 11.10.1. The fs_locations_server4 Structure . . . . . . . . . 251
11.10.2. The fs_locations_info4 Structure . . . . . . . . . . 255 11.10.2. The fs_locations_info4 Structure . . . . . . . . . . 256
11.10.3. The fs_locations_item4 Structure . . . . . . . . . . 256 11.10.3. The fs_locations_item4 Structure . . . . . . . . . . 257
11.11. The Attribute fs_status . . . . . . . . . . . . . . . . 258 11.11. The Attribute fs_status . . . . . . . . . . . . . . . . 259
12. Parallel NFS (pNFS) . . . . . . . . . . . . . . . . . . . . . 262 12. Parallel NFS (pNFS) . . . . . . . . . . . . . . . . . . . . . 263
12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 262 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 263
12.2. pNFS Definitions . . . . . . . . . . . . . . . . . . . . 264 12.2. pNFS Definitions . . . . . . . . . . . . . . . . . . . . 264
12.2.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 264 12.2.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 265
12.2.2. Metadata Server . . . . . . . . . . . . . . . . . . 264 12.2.2. Metadata Server . . . . . . . . . . . . . . . . . . 265
12.2.3. pNFS Client . . . . . . . . . . . . . . . . . . . . 265 12.2.3. pNFS Client . . . . . . . . . . . . . . . . . . . . 265
12.2.4. Storage Device . . . . . . . . . . . . . . . . . . . 265 12.2.4. Storage Device . . . . . . . . . . . . . . . . . . . 265
12.2.5. Storage Protocol . . . . . . . . . . . . . . . . . . 265 12.2.5. Storage Protocol . . . . . . . . . . . . . . . . . . 265
12.2.6. Control Protocol . . . . . . . . . . . . . . . . . . 265 12.2.6. Control Protocol . . . . . . . . . . . . . . . . . . 266
12.2.7. Layout Types . . . . . . . . . . . . . . . . . . . . 265 12.2.7. Layout Types . . . . . . . . . . . . . . . . . . . . 266
12.2.8. Layout . . . . . . . . . . . . . . . . . . . . . . . 266 12.2.8. Layout . . . . . . . . . . . . . . . . . . . . . . . 267
12.2.9. Layout Iomode . . . . . . . . . . . . . . . . . . . 266 12.2.9. Layout Iomode . . . . . . . . . . . . . . . . . . . 267
12.2.10. Device IDs . . . . . . . . . . . . . . . . . . . . . 267 12.2.10. Device IDs . . . . . . . . . . . . . . . . . . . . . 268
12.3. pNFS Operations . . . . . . . . . . . . . . . . . . . . 268 12.3. pNFS Operations . . . . . . . . . . . . . . . . . . . . 269
12.4. pNFS Attributes . . . . . . . . . . . . . . . . . . . . 269 12.4. pNFS Attributes . . . . . . . . . . . . . . . . . . . . 270
12.5. Layout Semantics . . . . . . . . . . . . . . . . . . . . 269 12.5. Layout Semantics . . . . . . . . . . . . . . . . . . . . 270
12.5.1. Guarantees Provided by Layouts . . . . . . . . . . . 269 12.5.1. Guarantees Provided by Layouts . . . . . . . . . . . 270
12.5.2. Getting a Layout . . . . . . . . . . . . . . . . . . 271 12.5.2. Getting a Layout . . . . . . . . . . . . . . . . . . 271
12.5.3. Layout Stateid . . . . . . . . . . . . . . . . . . . 272 12.5.3. Layout Stateid . . . . . . . . . . . . . . . . . . . 272
12.5.4. Committing a Layout . . . . . . . . . . . . . . . . 273 12.5.4. Committing a Layout . . . . . . . . . . . . . . . . 273
12.5.5. Recalling a Layout . . . . . . . . . . . . . . . . . 276 12.5.5. Recalling a Layout . . . . . . . . . . . . . . . . . 276
12.5.6. Revoking Layouts . . . . . . . . . . . . . . . . . . 283 12.5.6. Revoking Layouts . . . . . . . . . . . . . . . . . . 283
12.5.7. Metadata Server Write Propagation . . . . . . . . . 283 12.5.7. Metadata Server Write Propagation . . . . . . . . . 284
12.6. pNFS Mechanics . . . . . . . . . . . . . . . . . . . . . 283 12.6. pNFS Mechanics . . . . . . . . . . . . . . . . . . . . . 284
12.7. Recovery . . . . . . . . . . . . . . . . . . . . . . . . 285 12.7. Recovery . . . . . . . . . . . . . . . . . . . . . . . . 285
12.7.1. Recovery from Client Restart . . . . . . . . . . . . 285 12.7.1. Recovery from Client Restart . . . . . . . . . . . . 286
12.7.2. Dealing with Lease Expiration on the Client . . . . 286 12.7.2. Dealing with Lease Expiration on the Client . . . . 286
12.7.3. Dealing with Loss of Layout State on the Metadata 12.7.3. Dealing with Loss of Layout State on the Metadata
Server . . . . . . . . . . . . . . . . . . . . . . . 287 Server . . . . . . . . . . . . . . . . . . . . . . . 287
12.7.4. Recovery from Metadata Server Restart . . . . . . . 287 12.7.4. Recovery from Metadata Server Restart . . . . . . . 288
12.7.5. Operations During Metadata Server Grace Period . . . 289 12.7.5. Operations During Metadata Server Grace Period . . . 290
12.7.6. Storage Device Recovery . . . . . . . . . . . . . . 290 12.7.6. Storage Device Recovery . . . . . . . . . . . . . . 290
12.8. Metadata and Storage Device Roles . . . . . . . . . . . 290 12.8. Metadata and Storage Device Roles . . . . . . . . . . . 290
12.9. Security Considerations for pNFS . . . . . . . . . . . . 290 12.9. Security Considerations for pNFS . . . . . . . . . . . . 291
13. PNFS: NFSv4.1 File Layout Type . . . . . . . . . . . . . . . 291 13. PNFS: NFSv4.1 File Layout Type . . . . . . . . . . . . . . . 292
13.1. Client ID and Session Considerations . . . . . . . . . . 292 13.1. Client ID and Session Considerations . . . . . . . . . . 292
13.1.1. Sessions Considerations for Data Servers . . . . . . 294 13.1.1. Sessions Considerations for Data Servers . . . . . . 294
13.2. File Layout Definitions . . . . . . . . . . . . . . . . 294 13.2. File Layout Definitions . . . . . . . . . . . . . . . . 295
13.3. File Layout Data Types . . . . . . . . . . . . . . . . . 295 13.3. File Layout Data Types . . . . . . . . . . . . . . . . . 296
13.4. Interpreting the File Layout . . . . . . . . . . . . . . 299 13.4. Interpreting the File Layout . . . . . . . . . . . . . . 300
13.4.1. Determining the Stripe Unit Number . . . . . . . . . 299 13.4.1. Determining the Stripe Unit Number . . . . . . . . . 300
13.4.2. Interpreting the File Layout Using Sparse Packing . 299 13.4.2. Interpreting the File Layout Using Sparse Packing . 300
13.4.3. Interpreting the File Layout Using Dense Packing . . 302 13.4.3. Interpreting the File Layout Using Dense Packing . . 302
13.4.4. Sparse and Dense Stripe Unit Packing . . . . . . . . 304 13.4.4. Sparse and Dense Stripe Unit Packing . . . . . . . . 305
13.5. Data Server Multipathing . . . . . . . . . . . . . . . . 306 13.5. Data Server Multipathing . . . . . . . . . . . . . . . . 306
13.6. Operations Sent to NFSv4.1 Data Servers . . . . . . . . 307 13.6. Operations Sent to NFSv4.1 Data Servers . . . . . . . . 307
13.7. COMMIT Through Metadata Server . . . . . . . . . . . . . 309 13.7. COMMIT Through Metadata Server . . . . . . . . . . . . . 310
13.8. The Layout Iomode . . . . . . . . . . . . . . . . . . . 311 13.8. The Layout Iomode . . . . . . . . . . . . . . . . . . . 311
13.9. Metadata and Data Server State Coordination . . . . . . 311 13.9. Metadata and Data Server State Coordination . . . . . . 311
13.9.1. Global Stateid Requirements . . . . . . . . . . . . 311 13.9.1. Global Stateid Requirements . . . . . . . . . . . . 311
13.9.2. Data Server State Propagation . . . . . . . . . . . 312 13.9.2. Data Server State Propagation . . . . . . . . . . . 312
13.10. Data Server Component File Size . . . . . . . . . . . . 314 13.10. Data Server Component File Size . . . . . . . . . . . . 314
13.11. Layout Revocation and Fencing . . . . . . . . . . . . . 315 13.11. Layout Revocation and Fencing . . . . . . . . . . . . . 315
13.12. Security Considerations for the File Layout Type . . . . 315 13.12. Security Considerations for the File Layout Type . . . . 316
14. Internationalization . . . . . . . . . . . . . . . . . . . . 316 14. Internationalization . . . . . . . . . . . . . . . . . . . . 317
14.1. Stringprep profile for the utf8str_cs type . . . . . . . 317 14.1. Stringprep profile for the utf8str_cs type . . . . . . . 318
14.2. Stringprep profile for the utf8str_cis type . . . . . . 319 14.2. Stringprep profile for the utf8str_cis type . . . . . . 319
14.3. Stringprep profile for the utf8str_mixed type . . . . . 320 14.3. Stringprep profile for the utf8str_mixed type . . . . . 321
14.4. UTF-8 Capabilities . . . . . . . . . . . . . . . . . . . 322 14.4. UTF-8 Capabilities . . . . . . . . . . . . . . . . . . . 322
14.5. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 322 14.5. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 322
15. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 323 15. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 323
15.1. Error Definitions . . . . . . . . . . . . . . . . . . . 323 15.1. Error Definitions . . . . . . . . . . . . . . . . . . . 323
15.1.1. General Errors . . . . . . . . . . . . . . . . . . . 325 15.1.1. General Errors . . . . . . . . . . . . . . . . . . . 325
15.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 327 15.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 327
15.1.3. Compound Structure Errors . . . . . . . . . . . . . 328 15.1.3. Compound Structure Errors . . . . . . . . . . . . . 328
15.1.4. File System Errors . . . . . . . . . . . . . . . . . 330 15.1.4. File System Errors . . . . . . . . . . . . . . . . . 330
15.1.5. State Management Errors . . . . . . . . . . . . . . 332 15.1.5. State Management Errors . . . . . . . . . . . . . . 332
15.1.6. Security Errors . . . . . . . . . . . . . . . . . . 333 15.1.6. Security Errors . . . . . . . . . . . . . . . . . . 333
15.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 333 15.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 334
15.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 334 15.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 334
15.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 335 15.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 336
15.1.10. pNFS Errors . . . . . . . . . . . . . . . . . . . . 336 15.1.10. pNFS Errors . . . . . . . . . . . . . . . . . . . . 336
15.1.11. Session Use Errors . . . . . . . . . . . . . . . . . 337 15.1.11. Session Use Errors . . . . . . . . . . . . . . . . . 338
15.1.12. Session Management Errors . . . . . . . . . . . . . 338 15.1.12. Session Management Errors . . . . . . . . . . . . . 339
15.1.13. Client Management Errors . . . . . . . . . . . . . . 339 15.1.13. Client Management Errors . . . . . . . . . . . . . . 339
15.1.14. Delegation Errors . . . . . . . . . . . . . . . . . 340 15.1.14. Delegation Errors . . . . . . . . . . . . . . . . . 340
15.1.15. Attribute Handling Errors . . . . . . . . . . . . . 340 15.1.15. Attribute Handling Errors . . . . . . . . . . . . . 341
15.1.16. Obsoleted Errors . . . . . . . . . . . . . . . . . . 341 15.1.16. Obsoleted Errors . . . . . . . . . . . . . . . . . . 341
15.2. Operations and their valid errors . . . . . . . . . . . 342 15.2. Operations and their valid errors . . . . . . . . . . . 342
15.3. Callback operations and their valid errors . . . . . . . 358 15.3. Callback operations and their valid errors . . . . . . . 358
15.4. Errors and the operations that use them . . . . . . . . 360 15.4. Errors and the operations that use them . . . . . . . . 360
16. NFSv4.1 Procedures . . . . . . . . . . . . . . . . . . . . . 374 16. NFSv4.1 Procedures . . . . . . . . . . . . . . . . . . . . . 374
16.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 374 16.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 374
16.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 375 16.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 375
17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . 385 17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . 385
18. NFSv4.1 Operations . . . . . . . . . . . . . . . . . . . . . 388 18. NFSv4.1 Operations . . . . . . . . . . . . . . . . . . . . . 388
18.1. Operation 3: ACCESS - Check Access Rights . . . . . . . 388 18.1. Operation 3: ACCESS - Check Access Rights . . . . . . . 388
skipping to change at page 215, line 33 skipping to change at page 215, line 33
Use of such multi-server namespaces is OPTIONAL however, and for many Use of such multi-server namespaces is OPTIONAL however, and for many
purposes, single-server namespace are perfectly acceptable. Use of purposes, single-server namespace are perfectly acceptable. Use of
multi-server namespaces can provide many advantages, however, by multi-server namespaces can provide many advantages, however, by
separating a file system's logical position in a namespace from the separating a file system's logical position in a namespace from the
(possibly changing) logistical and administrative considerations that (possibly changing) logistical and administrative considerations that
result in particular file systems being located on particular result in particular file systems being located on particular
servers. servers.
11.1. Location Attributes 11.1. Location Attributes
NFSv4 contains RECOMMENDED attributes that allow file systems on one NFSv4.1 contains RECOMMENDED attributes that allow file systems on
server to be associated with one or more instances of that file one server to be associated with one or more instances of that file
system on other servers. These attributes specify such file system system on other servers. These attributes specify such file system
instances by specifying a server address target (either as a DNS name instances by specifying a server address target (either as a DNS name
representing one or more IP addresses or as a literal IP address) representing one or more IP addresses or as a literal IP address)
together with the path of that file system within the associated together with the path of that file system within the associated
single-server namespace. single-server namespace.
The fs_locations_info RECOMMENDED attribute allows specification of The fs_locations_info RECOMMENDED attribute allows specification of
one or more file system instance locations where the data one or more file system instance locations where the data
corresponding to a given file system may be found. This attribute corresponding to a given file system may be found. This attribute
provides to the client, in addition to information about file system provides to the client, in addition to information about file system
skipping to change at page 216, line 11 skipping to change at page 216, line 11
multiple file system instances, when and if that should be necessary. multiple file system instances, when and if that should be necessary.
The fs_locations RECOMMENDED attribute is inherited from NFSv4.0 and The fs_locations RECOMMENDED attribute is inherited from NFSv4.0 and
only allows specification of the file system locations where the data only allows specification of the file system locations where the data
corresponding to a given file system may be found. Servers SHOULD corresponding to a given file system may be found. Servers SHOULD
make this attribute available whenever fs_locations_info is make this attribute available whenever fs_locations_info is
supported, but client use of fs_locations_info is to be preferred. supported, but client use of fs_locations_info is to be preferred.
11.2. File System Presence or Absence 11.2. File System Presence or Absence
A given location in an NFSv4 namespace (typically but not necessarily A given location in an NFSv4.1 namespace (typically but not
a multi-server namespace) can have a number of file system instance necessarily a multi-server namespace) can have a number of file
locations associated with it (via the fs_locations or system instance locations associated with it (via the fs_locations or
fs_locations_info attribute). There may also be an actual current fs_locations_info attribute). There may also be an actual current
file system at that location, accessible via normal namespace file system at that location, accessible via normal namespace
operations (e.g. LOOKUP). In this case, the file system is said to operations (e.g. LOOKUP). In this case, the file system is said to
be "present" at that position in the namespace and clients will be "present" at that position in the namespace and clients will
typically use it, reserving use of additional locations specified via typically use it, reserving use of additional locations specified via
the location-related attributes to situations in which the principal the location-related attributes to situations in which the principal
location is no longer available. location is no longer available.
When there is no actual file system at the namespace location in When there is no actual file system at the namespace location in
question, the file system is said to be "absent". An absent file question, the file system is said to be "absent". An absent file
skipping to change at page 219, line 50 skipping to change at page 219, line 50
error and at that point the successor locations (typically only one error and at that point the successor locations (typically only one
but multiple choices are possible) can be fetched and used to but multiple choices are possible) can be fetched and used to
continue access. Transfer of the file system contents to the new continue access. Transfer of the file system contents to the new
location is referred to as "migration", but it should be kept in mind location is referred to as "migration", but it should be kept in mind
that there are cases in which this term can be used, like that there are cases in which this term can be used, like
"replication", when there is no actual data migration per se. "replication", when there is no actual data migration per se.
Where a file system was not previously present, specification of file Where a file system was not previously present, specification of file
system location provides a means by which file systems located on one system location provides a means by which file systems located on one
server can be associated with a namespace defined by another server, server can be associated with a namespace defined by another server,
thus allowing a general multi-server namespace facility. Designation thus allowing a general multi-server namespace facility. A
of such a location, in place of an absent file system, is called designation of such a location, in place of an absent file system, is
"referral". called a "referral".
Because client support for location-related attributes is OPTIONAL, a Because client support for location-related attributes is OPTIONAL, a
server may (but is not required to) take action to hide migration and server may (but is not required to) take action to hide migration and
referral events from such clients, by acting as a proxy, for example. referral events from such clients, by acting as a proxy, for example.
The server can determine the presence of client support from data The server can determine the presence of client support from the
passed in the EXCHANGE_ID operation (See Section 18.35.3). arguments of the EXCHANGE_ID operation (see Section 18.35.3).
11.4.1. File System Replication 11.4.1. File System Replication
The fs_locations and fs_locations_info attributes provide alternative The fs_locations and fs_locations_info attributes provide alternative
locations, to be used to access data in place of or in addition to locations, to be used to access data in place of or in addition to
the current file system instance. On first access to a file system, the current file system instance. On first access to a file system,
the client should obtain the value of the set of alternate locations the client should obtain the value of the set of alternate locations
by interrogating the fs_locations or fs_locations_info attribute, by interrogating the fs_locations or fs_locations_info attribute,
with the latter being preferred. with the latter being preferred.
skipping to change at page 222, line 44 skipping to change at page 222, line 44
also specify file system locations that include client-substituted also specify file system locations that include client-substituted
variables so that different clients are referred to different file variables so that different clients are referred to different file
systems (with different data contents) based on client attributes systems (with different data contents) based on client attributes
such as CPU architecture. such as CPU architecture.
When the fs_locations_info attribute indicates that there are When the fs_locations_info attribute indicates that there are
multiple possible targets listed, the relationships among them may be multiple possible targets listed, the relationships among them may be
important to the client in selecting the one to use. The same rules important to the client in selecting the one to use. The same rules
specified in Section 11.4.1 defining the appropriate standards for specified in Section 11.4.1 defining the appropriate standards for
the data propagation, apply to these multiple replicas as well. For the data propagation, apply to these multiple replicas as well. For
example, the client might prefer a writable that has additional example, the client might prefer a writable target on a server that
writable replicas to which it subsequently might switch. Note that, has additional writable replicas to which it subsequently might
as distinguished from the case of replication, there is no need to switch. Note that, as distinguished from the case of replication,
deal with the case of propagation of updates made by the current there is no need to deal with the case of propagation of updates made
client, since the current client has not accessed the file system in by the current client, since the current client has not accessed the
question. file system in question.
Use of multi-server namespaces is enabled by NFSv4 but is not Use of multi-server namespaces is enabled by NFSv4.1 but is not
required. The use of multi-server namespaces and their scope will required. The use of multi-server namespaces and their scope will
depend on the applications used, and system administration depend on the applications used, and system administration
preferences. preferences.
Multi-server namespaces can be established by a single server Multi-server namespaces can be established by a single server
providing a large set of referrals to all of the included file providing a large set of referrals to all of the included file
systems. Alternatively, a single multi-server namespace may be systems. Alternatively, a single multi-server namespace may be
administratively segmented with separate referral file systems (on administratively segmented with separate referral file systems (on
separate servers) for each separately-administered portion of the separate servers) for each separately-administered portion of the
namespace. Any segment or the top-level referral file system may use namespace. Any segment or the top-level referral file system may use
skipping to change at page 224, line 23 skipping to change at page 224, line 23
replication, and migration, care should be taken so that a user who replication, and migration, care should be taken so that a user who
mounts a given file system that includes a referral or a relocated mounts a given file system that includes a referral or a relocated
file system continues to see a coherent picture of that user-side file system continues to see a coherent picture of that user-side
file system despite the fact that it contains a number of server-side file system despite the fact that it contains a number of server-side
file systems which may be on different servers. file systems which may be on different servers.
One important issue is upward navigation from the root of a server- One important issue is upward navigation from the root of a server-
side file system to its parent (specified as ".." in UNIX), in the side file system to its parent (specified as ".." in UNIX), in the
case in which it transitions to that file system as a result of case in which it transitions to that file system as a result of
referral, migration, or a transition as a result of replication. referral, migration, or a transition as a result of replication.
When at such a point, and it needs to ascend to the parent, it must When the client is at such a point, and it needs to ascend to the
go back to the parent as seen within the multi-server namespace parent, it must go back to the parent as seen within the multi-server
rather issuing a LOOKUPP call to the server, which would result in namespace rather issuing a LOOKUPP call to the server, which would
the parent within that server's single-server namespace. In order to result in the parent within that server's single-server namespace.
do this, the client needs to remember the filehandles that represent In order to do this, the client needs to remember the filehandles
such file system roots, and use these instead of issuing a LOOKUPP to that represent such file system roots, and use these instead of
the current server. This will allow the client to present to issuing a LOOKUPP to the current server. This will allow the client
applications a consistent namespace, where upward navigation and to present to applications a consistent namespace, where upward
downward navigation are consistent. navigation and downward navigation are consistent.
Another issue concerns refresh of referral locations. When referrals Another issue concerns refresh of referral locations. When referrals
are used extensively, they may change as server configurations are used extensively, they may change as server configurations
change. It is expected that clients will cache information related change. It is expected that clients will cache information related
to traversing referrals so that future client side requests are to traversing referrals so that future client side requests are
resolved locally without server communication. This is usually resolved locally without server communication. This is usually
rooted in client-side name lookup caching. Clients should rooted in client-side name lookup caching. Clients should
periodically purge this data for referral points in order to detect periodically purge this data for referral points in order to detect
changes in location information. When the change_policy attribute changes in location information. When the change_policy attribute
changes for directories that hold referral entries or for the changes for directories that hold referral entries or for the
referral entries themselves, clients should consider any associated referral entries themselves, clients should consider any associated
cached referral information to be out of date. cached referral information to be out of date.
11.7. Effecting File System Transitions 11.7. Effecting File System Transitions
Transitions between file system instances, whether due to switching Transitions between file system instances, whether due to switching
between replicas upon server unavailability, or in response to between replicas upon server unavailability, or in response to
server-initiated migration events are best dealt with together. This server-initiated migration events are best dealt with together. This
is so even though for the server pragmatic considerations will is so even though for the server, pragmatic considerations will
normally force different implementation strategies for planned and normally force different implementation strategies for planned and
unplanned transitions. Even though the prototypical use cases of unplanned transitions. Even though the prototypical use cases of
replication and migration contain distinctive sets of features, when replication and migration contain distinctive sets of features, when
all possibilities for these operations are considered, there is an all possibilities for these operations are considered, there is an
underlying unity of these operations, from the client's point of underlying unity of these operations, from the client's point of
view, that makes treating them together desirable. view, that makes treating them together desirable.
A number of methods are possible for servers to replicate data and to A number of methods are possible for servers to replicate data and to
track client state in order to allow clients to transition between track client state in order to allow clients to transition between
file system instances with a minimum of disruption. Such methods file system instances with a minimum of disruption. Such methods
skipping to change at page 225, line 44 skipping to change at page 225, line 44
source and destination) belonging to a common class of any of several source and destination) belonging to a common class of any of several
types. Two file systems that belong to such a class share some types. Two file systems that belong to such a class share some
important aspect of file system behavior that clients may depend upon important aspect of file system behavior that clients may depend upon
when present, to easily effect a seamless transition between file when present, to easily effect a seamless transition between file
system instances. Conversely, where the file systems do not belong system instances. Conversely, where the file systems do not belong
to such a common class, the client has to deal with various sorts of to such a common class, the client has to deal with various sorts of
implementation discontinuities which may cause performance or other implementation discontinuities which may cause performance or other
issues in effecting a transition. issues in effecting a transition.
Where the fs_locations_info attribute is available, such file system Where the fs_locations_info attribute is available, such file system
classification data will be made directly available to the client. classification data will be made directly available to the client
See Section 11.10 for details. When only fs_locations is available, (see Section 11.10 for details). When only fs_locations is
default assumptions with regard to such classifications have to be available, default assumptions with regard to such classifications
inferred. See Section 11.9 for details. have to be inferred (see Section 11.9 for details).
In cases in which one server is expected to accept opaque values from In cases in which one server is expected to accept opaque values from
the client that originated from another server, the servers SHOULD the client that originated from another server, the servers SHOULD
encode the "opaque" values in big endian byte order. If this is encode the "opaque" values in big endian byte order. If this is
done, servers acting as replicas or immigrating file systems will be done, servers acting as replicas or immigrating file systems will be
able to parse values like stateids, directory cookies, filehandles, able to parse values like stateids, directory cookies, filehandles,
etc. even if their native byte order is different from that of other etc. even if their native byte order is different from that of other
servers cooperating in the replication and migration of the file servers cooperating in the replication and migration of the file
system. system.
11.7.1. File System Transitions and Simultaneous Access 11.7.1. File System Transitions and Simultaneous Access
When a single file system may be accessed at multiple locations, When a single file system may be accessed at multiple locations,
whether this is because of an indication of file system identity as whether this is because of an indication of file system identity as
reported by the fs_locations or fs_locations_info attributes or reported by the fs_locations or fs_locations_info attributes or
because two file systems instances have corresponding locations on because two file system instances have corresponding locations on
server addresses which connect to the same server (as indicated by a server addresses which connect to the same server (as indicated by a
common so_major_id field in the eir_server_owner field returned by common so_major_id field in the eir_server_owner field returned by
EXCHANGE_ID), the client will, depending on specific circumstances as EXCHANGE_ID), the client will, depending on specific circumstances as
discussed below, either: discussed below, either:
o The client accesses multiple instances simultaneously, as o The client accesses multiple instances simultaneously, as
representing alternate paths to the same data and metadata. representing alternate paths to the same data and metadata.
o The client accesses one instance (or set of instances) and then o The client accesses one instance (or set of instances) and then
transitions to an alternative instance (or set of instances) as a transitions to an alternative instance (or set of instances) as a
result of network issues, server unresponsiveness, or server- result of network issues, server unresponsiveness, or server-
directed migration. The transition may involve changes in directed migration. The transition may involve changes in
filehandles, fileids, the change attribute, and/or locking state, filehandles, fileids, the change attribute, and/or locking state,
depending on the attributes of the source and destination file depending on the attributes of the source and destination file
system instances, as specified in the fs_locations_info attribute. system instances, as specified in the fs_locations_info attribute.
Which of these choices is possible, and how a transition is effected, Which of these choices is possible, and how a transition is effected,
is governed by equivalence classes of file system instances as is governed by equivalence classes of file system instances as
reported by the fs_locations_info attribute, and, for file systems reported by the fs_locations_info attribute, and, for file system
instances in the same location within multiple single-server instances in the same location within a multiple single-server
namespace as indicated by the so_major_id field in the namespace as indicated by the so_major_id field in the
eir_server_owner field returned by EXCHANGE_ID. eir_server_owner field returned by EXCHANGE_ID.
11.7.2. Simultaneous Use and Transparent Transitions 11.7.2. Simultaneous Use and Transparent Transitions
When two file system instances have the same location within their When two file system instances have the same location within their
respective single-server namespaces and those two server network respective single-server namespaces and those two server network
addresses designate the same server (as indicated by the same addresses designate the same server (as indicated by the same
so_major_id value in the eir_server_owner value returned in response so_major_id value in the eir_server_owner value returned in response
to EXCHANGE_ID), those file systems instances can be treated as the to EXCHANGE_ID), those file systems instances can be treated as the
skipping to change at page 227, line 33 skipping to change at page 227, line 33
Where these conditions do not apply, a non-transparent file system Where these conditions do not apply, a non-transparent file system
instance transition is required with the details depending on the instance transition is required with the details depending on the
respective _handle_, _fileid_, _write-verifier_, _change_, _readdir_ respective _handle_, _fileid_, _write-verifier_, _change_, _readdir_
classes of the two file system instances and whether the two servers classes of the two file system instances and whether the two servers
address in question have the same eir_server_scope value as reported address in question have the same eir_server_scope value as reported
by EXCHANGE_ID. by EXCHANGE_ID.
11.7.2.1. Simultaneous Use of File System Instances 11.7.2.1. Simultaneous Use of File System Instances
When the conditions above hold, in either of the following two cases, When the conditions in Section 11.7.2 hold, in either of the
the client may use the two file system instances simultaneously. following two cases, the client may use the two file system instances
simultaneously.
o The fs_locations_info attribute does not contain separate per- o The fs_locations_info attribute does not contain separate per-
network-address entries for file systems instances at the distinct network-address entries for file systems instances at the distinct
network addresses. This includes the case in which the network addresses. This includes the case in which the
fs_locations_info attribute is unavailable. In this case, the fs_locations_info attribute is unavailable. In this case, the
fact that the two server addresses connect to the same server (as fact that the two server addresses connect to the same server (as
indicated by the two addresses sharing the same the so_major_id indicated by the two addresses sharing the same the so_major_id
value and subsequently confirmed as described in Section 2.10.4) value and subsequently confirmed as described in Section 2.10.4)
justifies simultaneous use and there is no fs_locations_info justifies simultaneous use and there is no fs_locations_info
attribute information contradicting that. attribute information contradicting that.
skipping to change at page 228, line 15 skipping to change at page 228, line 16
file systems and export their data in common. When simultaneous use file systems and export their data in common. When simultaneous use
is in effect, any change made to one file system instance must be is in effect, any change made to one file system instance must be
immediately reflected in the other file system instance(s). Locks immediately reflected in the other file system instance(s). Locks
are treated as part of a common lease, associated with a common are treated as part of a common lease, associated with a common
client ID. Depending on the details of the eir_server_owner returned client ID. Depending on the details of the eir_server_owner returned
by EXCHANGE_ID, the two server instances may be accessed by different by EXCHANGE_ID, the two server instances may be accessed by different
sessions or a single session in common. sessions or a single session in common.
11.7.2.2. Transparent File System Transitions 11.7.2.2. Transparent File System Transitions
When the conditions above hold and the fs_locations_info attribute When the conditions in Section 11.7.2.1 hold and the
explicitly shows the file system instances for these distinct network fs_locations_info attribute explicitly shows the file system
addresses as belonging to different _simultaneous-use_ classes, the instances for these distinct network addresses as belonging to
file system instances should not be used by the client different _simultaneous-use_ classes, the file system instances
simultaneously, but rather serially with one being used unless and should not be used by the client simultaneously, but rather serially
until communication difficulties, lack of responsiveness, or an with one being used unless and until communication difficulties, lack
explicit migration event causes another file system instance (or set of responsiveness, or an explicit migration event causes another file
of file system instances sharing a common _simultaneous-use_ class) system instance (or set of file system instances sharing a common
to be used. _simultaneous-use_ class) to be used.
When a change of file system instance is to be done, the client will When a change of file system instance is to be done, the client will
use the same client ID already in effect. If it already has use the same client ID already in effect. If it already has
connections to the new server address, these will be used. Otherwise connections to the new server address, these will be used. Otherwise
new connections to existing sessions or new sessions associated with new connections to existing sessions or new sessions associated with
the existing client ID are established as indicated by the the existing client ID are established as indicated by the
eir_server_owner returned by EXCHANGE_ID. eir_server_owner returned by EXCHANGE_ID.
In all such transparent transition cases, the following apply: In all such transparent transition cases, the following apply:
o Filehandles stay the same if persistent and if volatile are only o If filehandles are persistent they stay the same. If filehandles
subject to expiration, if they would be in the absence of file are volatile, they either stay the same, or if they expire, the
system transition. reason for expiration is not due to the file system transition.
o Fileid values do not change across the transition. o Fileid values do not change across the transition.
o The file system will have the same fsid in both the old and new o The file system will have the same fsid in both the old and new
locations. locations.
o Change attribute values are consistent across the transition and o Change attribute values are consistent across the transition and
do not have to be refetched. When change attributes indicate that do not have to be refetched. When change attributes indicate that
a cached object is still valid, it can remain cached. a cached object is still valid, it can remain cached.
skipping to change at page 229, line 38 skipping to change at page 229, line 39
file systems are reported as being in different _handle_ classes. In file systems are reported as being in different _handle_ classes. In
this case, all filehandles are assumed to expire as part of the file this case, all filehandles are assumed to expire as part of the file
system transition. Note that this behavior does not depend on system transition. Note that this behavior does not depend on
fh_expire_type attribute and supersedes the specification of fh_expire_type attribute and supersedes the specification of
FH4_VOL_MIGRATION bit, which only affects behavior when FH4_VOL_MIGRATION bit, which only affects behavior when
fs_locations_info is not available. fs_locations_info is not available.
When there is co-operation in filehandle assignment, the two file When there is co-operation in filehandle assignment, the two file
systems are reported as being in the same _handle_ classes. In this systems are reported as being in the same _handle_ classes. In this
case, persistent filehandles remain valid after the file system case, persistent filehandles remain valid after the file system
transition, while volatile filehandles (excluding those while are transition, while volatile filehandles (excluding those that are only
only volatile due to the FH4_VOL_MIGRATION bit) are subject to volatile due to the FH4_VOL_MIGRATION bit) are subject to expiration
expiration on the target server. on the target server.
11.7.4. Fileids and File System Transitions 11.7.4. Fileids and File System Transitions
In NFSv4.0, the issue of continuity of fileids in the event of a file In NFSv4.0, the issue of continuity of fileids in the event of a file
system transition was not addressed. The general expectation had system transition was not addressed. The general expectation had
been that in situations in which the two file system instances are been that in situations in which the two file system instances are
created by a single vendor using some sort of file system image copy, created by a single vendor using some sort of file system image copy,
fileids will be consistent across the transition while in the fileids will be consistent across the transition while in the
analogous multi-vendor transitions they will not. This poses analogous multi-vendor transitions they will not. This poses
difficulties, especially for the client without special knowledge of difficulties, especially for the client without special knowledge of
skipping to change at page 233, line 16 skipping to change at page 233, line 16
File systems co-operating in state management may actually share File systems co-operating in state management may actually share
state or simply divide the id space so as to recognize (and reject as state or simply divide the id space so as to recognize (and reject as
stale) each other's stateids and client IDs. Servers which do share stale) each other's stateids and client IDs. Servers which do share
state may not do so under all conditions or at all times. The state may not do so under all conditions or at all times. The
requirement for the server is that if it cannot be sure in accepting requirement for the server is that if it cannot be sure in accepting
a client ID that it reflects the locks the client was given, it must a client ID that it reflects the locks the client was given, it must
treat all associated state as stale and report it as such to the treat all associated state as stale and report it as such to the
client. client.
When the two file system instances are on servers that do not share a When the two file system instances are on servers that do not share a
server scope value the client must establish a new client ID on the server scope value, the client must establish a new client ID on the
destination, if it does not have one already, and reclaim locks if destination, if it does not have one already, and reclaim locks if
possible. In this case, old stateids and client IDs should not be possible. In this case, old stateids and client IDs should not be
presented to the new server since there is no assurance that they presented to the new server since there is no assurance that they
will not conflict with IDs valid on that server. will not conflict with IDs valid on that server.
In either case, when actual locks are not known to be maintained, the In either case, when actual locks are not known to be maintained, the
destination server may establish a grace period specific to the given destination server may establish a grace period specific to the given
file system, with non-reclaim locks being rejected for that file file system, with non-reclaim locks being rejected for that file
system, even though normal locks are being granted for other file system, even though normal locks are being granted for other file
systems. Clients should not infer the absence of a grace period for systems. Clients should not infer the absence of a grace period for
skipping to change at page 235, line 6 skipping to change at page 235, line 6
When a client receives an SEQ4_STATUS_LEASE_MOVED indication, it When a client receives an SEQ4_STATUS_LEASE_MOVED indication, it
should perform an operation on each file system associated with the should perform an operation on each file system associated with the
server where there is locking state for the current client associated server where there is locking state for the current client associated
with the file system in question. The client may choose to reference with the file system in question. The client may choose to reference
all file systems in the interests of simplicity but what is important all file systems in the interests of simplicity but what is important
is that it must reference all file systems for which there was is that it must reference all file systems for which there was
locking state where that state moved. Once the client receives an locking state where that state moved. Once the client receives an
NFS4ERR_MOVED error for each file system, the SEQ4_STATUS_LEASE_MOVED NFS4ERR_MOVED error for each file system, the SEQ4_STATUS_LEASE_MOVED
indication is cleared. The client can terminate the process of indication is cleared. The client can terminate the process of
checking file systems once this indication is cleared, since there checking file systems once this indication is cleared (but only if
are no others for which locking state has moved. the client has received a reply for all outstanding SEQUENCE requests
on all sessions it has with the server), since there are no others
for which locking state has moved.
A client may use GETATTR of the fs_status (or fs_locations_info) A client may use GETATTR of the fs_status (or fs_locations_info)
attribute on all of the file systems to get absence indications in a attribute on all of the file systems to get absence indications in a
single (or a few) request(s), since absent file systems will not single (or a few) request(s), since absent file systems will not
cause an error in this context. However, it still must do an cause an error in this context. However, it still must do an
operation which receives NFS4ERR_MOVED on each file system, or order operation which receives NFS4ERR_MOVED on each file system, in order
to clear the SEQ4_STATUS_LEASE_MOVED indication is cleared. to clear the SEQ4_STATUS_LEASE_MOVED indication is cleared.
Once the set of file systems with transferred locking state has been Once the set of file systems with transferred locking state has been
determined, the client can follow the normal process to obtain the determined, the client can follow the normal process to obtain the
new server information (through the fs_locations and new server information (through the fs_locations and
fs_locations_info attributes) and perform renewal of those leases on fs_locations_info attributes) and perform renewal of those leases on
the new server, unless information in fs_locations_info attribute the new server, unless information in fs_locations_info attribute
shows that no state could have been transferred. If the server has shows that no state could have been transferred. If the server has
not had state transferred to it transparently, the client will not had state transferred to it transparently, the client will
receive NFS4ERR_STALE_CLIENTID from the new server, as described receive NFS4ERR_STALE_CLIENTID from the new server, as described
skipping to change at page 237, line 43 skipping to change at page 237, line 45
o Where a file system is not writable but represents a read-only o Where a file system is not writable but represents a read-only
copy (possibly periodically updated) of a writable file system, copy (possibly periodically updated) of a writable file system,
clients have similar requirements with regard to the propagation clients have similar requirements with regard to the propagation
of updates. They may need a guarantee that any change visible on of updates. They may need a guarantee that any change visible on
the original file system instance must be immediately visible on the original file system instance must be immediately visible on
any replica before the client transitions access to that replica, any replica before the client transitions access to that replica,
in order to avoid any possibility that a client, in effecting a in order to avoid any possibility that a client, in effecting a
transition to a replica, will see any reversion in file system transition to a replica, will see any reversion in file system
state. The specific means by which this will be prevented varies state. The specific means by which this will be prevented varies
based on fs4_status_type reported as part of the fs_status based on fs4_status_type reported as part of the fs_status
attribute (See Section 11.11). Since these file systems are attribute (see Section 11.11). Since these file systems are
presumed not to be suitable for simultaneous use, there is no presumed not to be suitable for simultaneous use, there is no
specification of how locking is handled and it generally will be specification of how locking is handled and it generally will be
the case that locks obtained one file system will be separate from the case that locks obtained one file system will be separate from
those on others. Since these are going to be read-only file those on others. Since these are going to be read-only file
systems, this is not expected to pose an issue for clients or systems, this is not expected to pose an issue for clients or
applications. applications.
11.8. Effecting File System Referrals 11.8. Effecting File System Referrals
Referrals are effected when an absent file system is encountered, and Referrals are effected when an absent file system is encountered, and
skipping to change at page 239, line 37 skipping to change at page 239, line 37
Given the failure of the GETFH, the client has the job of determining Given the failure of the GETFH, the client has the job of determining
the root of the absent file system and where to find that file the root of the absent file system and where to find that file
system, i.e. the server and path relative to that server's root fh. system, i.e. the server and path relative to that server's root fh.
Note here that in this example, the client did not obtain filehandles Note here that in this example, the client did not obtain filehandles
and attribute information (e.g. fsid) for the intermediate and attribute information (e.g. fsid) for the intermediate
directories, so that it would not be sure where the absent file directories, so that it would not be sure where the absent file
system starts. It could be the case, for example, that /this/is/the system starts. It could be the case, for example, that /this/is/the
is the root of the moved file system and that the reason that the is the root of the moved file system and that the reason that the
lookup of "path" succeeded is that the file system was not absent on lookup of "path" succeeded is that the file system was not absent on
that op but was moved between the last LOOKUP and the GETFH (since that operation but was moved between the last LOOKUP and the GETFH
COMPOUND is not atomic). Even if we had the fsids for all of the (since COMPOUND is not atomic). Even if we had the fsids for all of
intermediate directories, we could have no way of knowing that /this/ the intermediate directories, we could have no way of knowing that
is/the/path was the root of a new file system, since we don't yet /this/is/the/path was the root of a new file system, since we don't
have its fsid. yet have its fsid.
In order to get the necessary information, let us re-send the chain In order to get the necessary information, let us re-send the chain
of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we
can be sure where the appropriate file system boundaries are. The can be sure where the appropriate file system boundaries are. The
client could choose to get fs_locations_info at the same time but in client could choose to get fs_locations_info at the same time but in
most cases the client will have a good guess as to where file system most cases the client will have a good guess as to where file system
boundaries are (because of where and where not NFS4ERR_MOVED was boundaries are (because of where and where not NFS4ERR_MOVED was
received) making fetching of fs_locations_info unnecessary. received) making fetching of fs_locations_info unnecessary.
OP01: PUTROOTFH --> NFS_OK OP01: PUTROOTFH --> NFS_OK
skipping to change at page 241, line 19 skipping to change at page 241, line 19
OP12: LOOKUP "path" --> NFS_OK OP12: LOOKUP "path" --> NFS_OK
- Current fh is for /this/is/the/path and is within a new, absent - Current fh is for /this/is/the/path and is within a new, absent
file system, but ... file system, but ...
- The client will never see the value of that fh - The client will never see the value of that fh
OP13: GETATTR(fsid, fs_locations_info) --> NFS_OK OP13: GETATTR(fsid, fs_locations_info) --> NFS_OK
- We are getting the fsid to know where the file system boundaries - We are getting the fsid to know where the file system boundaries
are. Note that the fsid we are given will not necessarily be are. In this operation the fsid will be different than that of
preserved at the new location. That fsid might be different and the parent directory (which in turn was retrieved in OP10). Note
in fact the fsid we have for this file system might be a valid that the fsid we are given will not necessarily be preserved at
fsid of a different file system on that new server. the new location. That fsid might be different and in fact the
fsid we have for this file system might be a valid fsid of a
different file system on that new server.
- In this particular case, we are pretty sure anyway that what has - In this particular case, we are pretty sure anyway that what has
moved is /this/is/the/path rather than /this/is/the since we have moved is /this/is/the/path rather than /this/is/the since we have
the fsid of the latter and it is that of the pseudo-fs, which the fsid of the latter and it is that of the pseudo-fs, which
presumably cannot move. However, in other examples, we might not presumably cannot move. However, in other examples, we might not
have this kind of information to rely on (e.g. /this/is/the might have this kind of information to rely on (e.g. /this/is/the might
be a non-pseudo file system separate from /this/is/the/path), so be a non-pseudo file system separate from /this/is/the/path), so
we need to have another reliable source information on the we need to have another reliable source information on the
boundary of the file system which is moved. If, for example, the boundary of the file system which is moved. If, for example, the
file system "/this/is" had moved we would have a case of migration file system "/this/is" had moved we would have a case of migration
skipping to change at page 241, line 50 skipping to change at page 241, line 52
still need the location information for that file system. still need the location information for that file system.
OP14: GETFH --> NFS4ERR_MOVED OP14: GETFH --> NFS4ERR_MOVED
- Fails because current fh is in an absent file system at the start - Fails because current fh is in an absent file system at the start
of the operation and the spec makes no exception for GETFH. Note of the operation and the spec makes no exception for GETFH. Note
that this means the server will never send the client a filehandle that this means the server will never send the client a filehandle
from within an absent file system. from within an absent file system.
Given the above, the client knows where the root of the absent file Given the above, the client knows where the root of the absent file
system is, by noting where the change of fsid occurred. The system is (/this/is/the/path), by noting where the change of fsid
fs_locations_info attribute also gives the client the actual location occurred (between "the" and "path"). The fs_locations_info attribute
of the absent file system, so that the referral can proceed. The also gives the client the actual location of the absent file system,
server gives the client the bare minimum of information about the so that the referral can proceed. The server gives the client the
absent file system so that there will be very little scope for bare minimum of information about the absent file system so that
problems of conflict between information sent by the referring server there will be very little scope for problems of conflict between
and information of the file system's home. No filehandles and very information sent by the referring server and information of the file
few attributes are present on the referring server and the client can system's home. No filehandles and very few attributes are present on
treat those it receives as basically transient information with the the referring server and the client can treat those it receives as
function of enabling the referral. basically transient information with the function of enabling the
referral.
11.8.2. Referral Example (READDIR) 11.8.2. Referral Example (READDIR)
Another context in which a client may encounter referrals is when it Another context in which a client may encounter referrals is when it
does a READDIR on directory in which some of the sub-directories are does a READDIR on directory in which some of the sub-directories are
the roots of absent file systems. the roots of absent file systems.
Suppose such a directory is read as follows: Suppose such a directory is read as follows:
o PUTROOTFH o PUTROOTFH
skipping to change at page 243, line 32 skipping to change at page 243, line 34
o LOOKUP "this" --> NFS_OK. The current fh is for /this and is o LOOKUP "this" --> NFS_OK. The current fh is for /this and is
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and
is within the pseudo-fs. is within the pseudo-fs.
o READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) o READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid)
--> NFS_OK. The attributes for "path" will only contain --> NFS_OK. The attributes for directory entry with the component
rdattr_error with the value NFS4ERR_MOVED, together with an fsid named "path" will only contain rdattr_error with the value
value and a value for mounted_on_fileid. NFS4ERR_MOVED, together with an fsid value and a value for
mounted_on_fileid.
So suppose we do another READDIR to get fs_locations_info (although So suppose we do another READDIR to get fs_locations_info (although
we could have used a GETATTR directly, as in Section 11.8.1). we could have used a GETATTR directly, as in Section 11.8.1).
o PUTROOTFH o PUTROOTFH
o LOOKUP "this" o LOOKUP "this"
o LOOKUP "is" o LOOKUP "is"
skipping to change at page 244, line 21 skipping to change at page 244, line 22
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and
is within the pseudo-fs. is within the pseudo-fs.
o READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid, o READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid,
size, time_modify) --> NFS_OK. The attributes will be as shown size, time_modify) --> NFS_OK. The attributes will be as shown
below. below.
The attributes for "path" will only contain The attributes for the directory entry with the component named
"path" will only contain
o rdattr_error (value: NFS_OK) o rdattr_error (value: NFS_OK)
o fs_locations_info o fs_locations_info
o mounted_on_fileid (value: unique fileid within referring file o mounted_on_fileid (value: unique fileid within referring file
system) system)
o fsid (value: unique value within referring server) o fsid (value: unique value within referring server)
The attribute entry for "path" will not contain size or time_modify The attributes for entry "path" will not contain size or time_modify
because these attributes are not available within an absent file because these attributes are not available within an absent file
system. system.
11.9. The Attribute fs_locations 11.9. The Attribute fs_locations
The fs_locations attribute is structured in the following way: The fs_locations attribute is structured in the following way:
struct fs_location4 { struct fs_location4 {
utf8str_cis server<>; utf8str_cis server<>;
pathname4 rootpath; pathname4 rootpath;
skipping to change at page 245, line 10 skipping to change at page 245, line 13
fs_location4 locations<>; fs_location4 locations<>;
}; };
The fs_location4 data type is used to represent the location of a The fs_location4 data type is used to represent the location of a
file system by providing a server name and the path to the root of file system by providing a server name and the path to the root of
the file system within that server's namespace. When a set of the file system within that server's namespace. When a set of
servers have corresponding file systems at the same path within their servers have corresponding file systems at the same path within their
namespaces, an array of server names may be provided. An entry in namespaces, an array of server names may be provided. An entry in
the server array is a UTF-8 string and represents one of a the server array is a UTF-8 string and represents one of a
traditional DNS host name, IPv4 address, or IPv6 address, or an zero- traditional DNS host name, IPv4 address, or IPv6 address, or an zero-
length string. A null string SHOULD be used to indicate the current length string. A zero-length string SHOULD be used to indicate the
address being used for the RPC call. It is not a requirement that current address being used for the RPC call. It is not a requirement
all servers that share the same rootpath be listed in one that all servers that share the same rootpath be listed in one
fs_location4 instance. The array of server names is provided for fs_location4 instance. The array of server names is provided for
convenience. Servers that share the same rootpath may also be listed convenience. Servers that share the same rootpath may also be listed
in separate fs_location4 entries in the fs_locations attribute. in separate fs_location4 entries in the fs_locations attribute.
The fs_locations4 data type and fs_location attribute contain an The fs_locations4 data type and fs_locations attribute contain an
array of such locations. Since the namespace of each server may be array of such locations. Since the namespace of each server may be
constructed differently, the "fs_root" field is provided. The path constructed differently, the "fs_root" field is provided. The path
represented by fs_root represents the location of the file system in represented by fs_root represents the location of the file system in
the current server's namespace, i.e. that of the server from which the current server's namespace, i.e. that of the server from which
the fs_locations attribute was obtained. The fs_root path is meant the fs_locations attribute was obtained. The fs_root path is meant
to aid the client by clearly referencing the root of the file system to aid the client by clearly referencing the root of the file system
whose locations are being reported, no matter what object within the whose locations are being reported, no matter what object within the
current file system the current filehandle designates. When the current file system the current filehandle designates. The fs_root
fs_locations attribute is interrogated and there are no alternate is simply the pathname the client used to reach the object on the
file system locations, the server SHOULD return a zero-length array current server, the object being that the fs_locations attribute
of fs_location4 structures, together with a valid fs_root. applies to.
When the fs_locations attribute is interrogated and there are no
alternate file system locations, the server SHOULD return a zero-
length array of fs_location4 structures, together with a valid
fs_root.
As an example, suppose there is a replicated file system located at As an example, suppose there is a replicated file system located at
two servers (servA and servB). At servA, the file system is located two servers (servA and servB). At servA, the file system is located
at path "/a/b/c". At, servB the file system is located at path at path "/a/b/c". At, servB the file system is located at path
"/x/y/z". If the client were to obtain the fs_locations value for "/x/y/z". If the client were to obtain the fs_locations value for
the directory at "/a/b/c/d", it might not necessarily know that the the directory at "/a/b/c/d", it might not necessarily know that the
file system's root is located in servA's namespace at "/a/b/c". When file system's root is located in servA's namespace at "/a/b/c". When
the client switches to servB, it will need to determine that the the client switches to servB, it will need to determine that the
directory it first referenced at servA is now represented by the path directory it first referenced at servA is now represented by the path
"/x/y/z/d" on servB. To facilitate this, the fs_locations attribute "/x/y/z/d" on servB. To facilitate this, the fs_locations attribute
provided by servA would have a fs_root value of "/a/b/c" and two provided by servA would have a fs_root value of "/a/b/c" and two
entries in fs_locations. One entry in fs_locations will be for entries in fs_locations. One entry in fs_locations will be for
itself (servA) and the other will be for servB with a path of itself (servA) and the other will be for servB with a path of
"/x/y/z". With this information, the client is able to substitute "/x/y/z". With this information, the client is able to substitute
"/x/y/z" for the "/a/b/c" at the beginning of its access path and "/x/y/z" for the "/a/b/c" at the beginning of its access path and
construct "/x/y/z/d" to use for the new server. construct "/x/y/z/d" to use for the new server.
Since fs_locations attribute lacks information defining various Note that: there is no requirement that the number of components in
each rootpath be the same; there is no relation between the number of
components in rootpath or fs_root; and the none of the components in
each rootpath and fs_root have to be the same. In the above example,
we could have had a third element in the locations array, with server
equal to "servC", and rootpath equal to "/I/II", and a fourth element
in locations with server equal to "servD", and rootpath equal to
"/aleph/beth/gimel/daleth/he".
The relationship between fs_root to a rootpath is that the client
replaces the pathname indicated in fs_root for the current server for
the substitute indicated in rootpath for the new server.
For an example for a referred or migrated file system, suppose there
is a file system located at serv1. At serv1, the file system is
located at "/az/buky/vedi/glagoli". The client finds that object at
"glagoli" has migrated (or is a referral). The client gets the
fs_locations attribute, which contains an fs_root of "/az/buky/vedi/
glagoli", and one element in the locations array, with server equal
to "serv2", and rootpath equal to "/izhitsa/fita". The client
replaces "/az/buky/vedi/glagoli" with "/izhitsa/fita", and uses the
latter pathname on "serv2".
Thus, the server MUST return an fs_root that is equal to the path the
client used to reach the object the fs_locations attribute applies
to. Otherwise the client cannot determine the new path to use on the
new server.
Since the fs_locations attribute lacks information defining various
attributes of the various file system choices presented, it SHOULD attributes of the various file system choices presented, it SHOULD
only be interrogated and used when fs_locations_info is not only be interrogated and used when fs_locations_info is not
available. When fs_locations is used, information about the specific available. When fs_locations is used, information about the specific
locations should be assumed based on the following rules. locations should be assumed based on the following rules.
The following rules are general and apply irrespective of the The following rules are general and apply irrespective of the
context. context.
o All listed file system instances should be considered as of the o All listed file system instances should be considered as of the
same _handle_ class, if and only if, the current fh_expire_type same _handle_ class, if and only if, the current fh_expire_type
skipping to change at page 248, line 20 skipping to change at page 249, line 6
It should be noted that fs_locations_info attributes returned by It should be noted that fs_locations_info attributes returned by
servers for various replicas may different for various reasons. One servers for various replicas may different for various reasons. One
server may know about a set of replicas that are not know to other server may know about a set of replicas that are not know to other
servers. Further, compatibility attributes may differ. Filehandles servers. Further, compatibility attributes may differ. Filehandles
may by of the same class going from replica A to replica B but not may by of the same class going from replica A to replica B but not
going in the reverse direction. This may happen because the going in the reverse direction. This may happen because the
filehandles are the same but the server implementation for the server filehandles are the same but the server implementation for the server
on which replica B may not have provision to note and report that on which replica B may not have provision to note and report that
equivalence. equivalence.
The fs_locations_info attribute consists of a root pathname (just The fs_locations_info attribute consists of a root pathname
like fs_locations), together with an array of fs_location_item4 (fli_fs_root, just like fs_root in the fs_locations attribute),
structures. The fs_location_item4 structures in turn consist of a together with an array of fs_location_item4 structures. The
root pathname together with an array of fs_location_item4 structures in turn consist of a root pathname
(fli_rootpath) together with an array (fli_entries) of elements of
data type fs_locations_server4, all defined as follows.
/* /*
* Defines an individual server replica * Defines an individual server replica
*/ */
struct fs_locations_server4 { struct fs_locations_server4 {
int32_t fls_currency; int32_t fls_currency;
opaque fls_info<>; opaque fls_info<>;
utf8str_cis fls_server; utf8str_cis fls_server;
}; };
skipping to change at page 250, line 39 skipping to change at page 251, line 29
instead serve as a hint about how far the copy of the data would instead serve as a hint about how far the copy of the data would
be expected to be behind the most up-to-date copy. be expected to be behind the most up-to-date copy.
o A counted array of one-byte values (fls_info) containing o A counted array of one-byte values (fls_info) containing
information about the particular file system instance. This data information about the particular file system instance. This data
includes general flags, transport capability flags, file system includes general flags, transport capability flags, file system
equivalence class information, and selection priority information. equivalence class information, and selection priority information.
The encoding will be discussed below. The encoding will be discussed below.
o The server string (fls_server). For the case of the replica o The server string (fls_server). For the case of the replica
currently being accessed (via GETATTR), a null string MAY be used currently being accessed (via GETATTR), a zero-length string MAY
to indicate the current address being used for the RPC call. be used to indicate the current address being used for the RPC
call.
Data within the fls_info array is in the form of 8-bit data items Data within the fls_info array is in the form of 8-bit data items
with constants giving the offsets within the array of various values with constants giving the offsets within the array of various values
describing this particular file system instance. This style of describing this particular file system instance. This style of
definition was chosen, in preference to explicit XDR structure definition was chosen, in preference to explicit XDR structure
definitions for these values, for a number of reasons. definitions for these values, for a number of reasons.
o The kinds of data in the fls_info array, representing flags, file o The kinds of data in the fls_info array, representing flags, file
system classes and priorities among set of file systems system classes and priorities among set of file systems
representing the same data, are such that eight bits provides a representing the same data, are such that eight bits provides a
skipping to change at page 254, line 19 skipping to change at page 255, line 11
continuous-with the current one in a given respect but the continuous-with the current one in a given respect but the
information should be available also as to whether two other replicas information should be available also as to whether two other replicas
match in that respect as well. match in that respect as well.
The following fields specify the file system's class numbers for the The following fields specify the file system's class numbers for the
equivalence relations used in determining the nature of file system equivalence relations used in determining the nature of file system
transitions. See Section 11.7 for details about how this information transitions. See Section 11.7 for details about how this information
is to be used. Servers may assign these values as they wish, so long is to be used. Servers may assign these values as they wish, so long
as file system instances that share the same value have the specified as file system instances that share the same value have the specified
relationship to one another, conversely file systems which have the relationship to one another, conversely file systems which have the
specified relationship to one another share a common class value. A specified relationship to one another share a common class value. As
simple to provide this data assumes that the server has knowledge of each instance entry is added, the relationships of this instance to
the appropriate set of identity relationships to be encoded. As each
instance entry is added, the relationships of this instance to
previously entered instances can be consulted and if one is found previously entered instances can be consulted and if one is found
that bears the specified relationship, that entry's class value can that bears the specified relationship, that entry's class value can
be copied to the new entry. When no such previous entry exists, a be copied to the new entry. When no such previous entry exists, a
new value for that byte index, not previously used can be selected, new value for that byte index, not previously used can be selected,
most likely by increment the value of the last class value assigned most likely by increment the value of the last class value assigned
for that index. for that index.
o The field with byte index FSLI4BX_CLSIMUL defines the o The field with byte index FSLI4BX_CLSIMUL defines the
simultaneous-use class for the file system. simultaneous-use class for the file system.
skipping to change at page 259, line 21 skipping to change at page 260, line 4
}; };
struct fs4_status { struct fs4_status {
bool fss_absent; bool fss_absent;
fs4_status_type fss_type; fs4_status_type fss_type;
utf8str_cs fss_source; utf8str_cs fss_source;
utf8str_cs fss_current; utf8str_cs fss_current;
int32_t fss_age; int32_t fss_age;
nfstime4 fss_version; nfstime4 fss_version;
}; };
The boolean fss_absent indicates whether the file system is currently The boolean fss_absent indicates whether the file system is currently
absent. This value will be set if the file system was previously absent. This value will be set if the file system was previously
present and becomes absent, or if the file system has never been present and becomes absent, or if the file system has never been
present and the type is STATUS4_REFERRAL. When this boolean is set present and the type is STATUS4_REFERRAL. When this boolean is set
and the type is not STATUS4_REFERRAL, the remaining information in and the type is not STATUS4_REFERRAL, the remaining information in
the fs4_status reflects that last valid when the file system was the fs4_status reflects that last valid when the file system was
present. present.
The type value indicates the kind of file system image represented. The fss_type field indicates the kind of file system image
This is of particular importance when using the version values to represented. This is of particular importance when using the version
determine appropriate succession of file system images. When values to determine appropriate succession of file system images.
fss_absent is set, and the file system was previously present, the When fss_absent is set, and the file system was previously present,
type reflected is that when the file was last present. Five types the value of fss_type reflected is that when the file was last
are distinguished: present. Five values are distinguished:
o STATUS4_FIXED which indicates a read-only image in the sense that o STATUS4_FIXED which indicates a read-only image in the sense that
it will never change. The possibility is allowed that, as a it will never change. The possibility is allowed that, as a
result of migration or switch to a different image, changed data result of migration or switch to a different image, changed data
can be accessed, but within the confines of this instance, no can be accessed, but within the confines of this instance, no
change is allowed. The client can use this fact to cache change is allowed. The client can use this fact to cache
aggressively. aggressively.
o STATUS4_VERSIONED which indicates that the image, like the o STATUS4_VERSIONED which indicates that the image, like the
STATUS4_UPDATED case, is updated exogenously, but it provides a STATUS4_UPDATED case, is updated externally, but it provides a
guarantee that the server will carefully update an associated guarantee that the server will carefully update an associated
version value so that the client can protect itself from a version value so that the client can protect itself from a
situation in which it reads data from one version of the file situation in which it reads data from one version of the file
system, and then later reads data from an earlier version of the system, and then later reads data from an earlier version of the
same file system. See below for a discussion of how this can be same file system. See below for a discussion of how this can be
done. done.
o STATUS4_UPDATED which indicates an image that cannot be updated by o STATUS4_UPDATED which indicates an image that cannot be updated by
the user writing to it but may be changed exogenously, typically the user writing to it but may be changed externally, typically
because it is a periodically updated copy of another writable file because it is a periodically updated copy of another writable file
system somewhere else. In this case, version information is not system somewhere else. In this case, version information is not
provided and the client does not have the responsibility of making provided and the client does not have the responsibility of making
sure that this version only advances upon a file system instance sure that this version only advances upon a file system instance
transition. In this case, it is the responsibility of the server transition. In this case, it is the responsibility of the server
to make sure that the data presented after a file system instance to make sure that the data presented after a file system instance
transition is a proper successor image and includes all changes transition is a proper successor image and includes all changes
seen by the client and any change made before all such changes. seen by the client and any change made before all such changes.
o STATUS4_WRITABLE which indicates that the file system is an actual o STATUS4_WRITABLE which indicates that the file system is an actual
writable one. The client need not, of course, actually write to writable one. The client need not, of course, actually write to
the file system, but once it does, it should not accept a the file system, but once it does, it should not accept a
transition to anything other than a writable instance of that same transition to anything other than a writable instance of that same
file system. file system.
o STATUS4_REFERRAL which indicates that the file system is question o STATUS4_REFERRAL which indicates that the file system is question
is absent and has never been present on this server. is absent and has never been present on this server.
Note that in the STATUS4_UPDATED and STATUS4_VERSIONED cases, the Note that in the STATUS4_UPDATED and STATUS4_VERSIONED cases, the
server is responsible for the appropriate handling of locks that are server is responsible for the appropriate handling of locks that are
inconsistent with exogenous changes to delegations. If a server inconsistent with external changes to delegations. If a server gives
gives out delegations, they SHOULD be returned if a before a change out delegations, they SHOULD be recalled before an inconsistent
which is inconsistent is made to data, and MUST be revoked if this is change made to data, and MUST be revoked if this is not possible.
not possible. Similarly, if an open is inconsistent with data that Similarly, if an open is inconsistent with data that is changed (the
is changed (the open denies WRITE and the data is changed), that lock open denies WRITE and the data is changed), that lock SHOULD be
SHOULD be considered administratively revoked. considered administratively revoked.
The opaque strings source and current provide a way of presenting The opaque strings fss_source and fss_current provide a way of
information about the source of the file system image being present. presenting information about the source of the file system image
It is not intended that client do anything with this information being present. It is not intended that client do anything with this
other than make it available to administrative tools. It is intended information other than make it available to administrative tools. It
that this information be helpful when researching possible problems is intended that this information be helpful when researching
with a file system image that might arise when it is unclear if the possible problems with a file system image that might arise when it
correct image is being accessed and if not, how that image came to be is unclear if the correct image is being accessed and if not, how
made. This kind of debugging information will be helpful, if, as that image came to be made. This kind of dianostic information will
seems likely, copies of file systems are made in many different ways be helpful, if, as seems likely, copies of file systems are made in
(e.g. simple user-level copies, file system-level point-in-time many different ways (e.g. simple user-level copies, file system-level
copies, clones of the underlying storage), under a variety of point-in-time copies, clones of the underlying storage), under a
administrative arrangements. In such environments, determining how a variety of administrative arrangements. In such environments,
given set of data was constructed can be very helpful in resolving determining how a given set of data was constructed can be very
problems. helpful in resolving problems.
The opaque string 'source' is used to indicate the source of a given The opaque string fss_source is used to indicate the source of a
file system with the expectation that tools capable of creating a given file system with the expectation that tools capable of creating
file system image propagate this information, when that is possible. a file system image propagate this information, when that is
It is understood that this may not always be possible since a user- possible. It is understood that this may not always be possible
level copy may be thought of as creating a new data set and the tools since a user-level copy may be thought of as creating a new data set
used may have no mechanism to propagate this data. When a file and the tools used may have no mechanism to propagate this data.
system is initially created, it is desirable to associate with it When a file system is initially created, it is desirable to associate
data regarding how the file system was created, where it was created, with it data regarding how the file system was created, where it was
by whom, etc. Making this information available in this attribute in created, by whom, etc. Making this information available in this
a human-readable string form will be helpful for applications and attribute in a human-readable string form will be helpful for
system administrators and also serves to make it available when the applications and system administrators and also serves to make it
original file system is used to make subsequent copies. available when the original file system is used to make subsequent
copies.
The opaque string 'current' should provide whatever information is The opaque string fss_current should provide whatever information is
available about the source of the current copy. Such information as available about the source of the current copy. Such information as
the tool creating it, any relevant parameters to that tool, the time the tool creating it, any relevant parameters to that tool, the time
at which the copy was done, the user making the change, the server on at which the copy was done, the user making the change, the server on
which the change was made, etc. All information should be in a which the change was made, etc. All information should be in a
human-readable string form. human-readable string form.
The age provides an indication of how out-of-date the file system The field fss_age provides an indication of how out-of-date the file
currently is with respect to its ultimate data source (in case of system currently is with respect to its ultimate data source (in case
cascading data updates). This complements the fls_currency field of of cascading data updates). This complements the fls_currency field
fs_locations_server4 (See Section 11.10) in the following way: the of fs_locations_server4 (see Section 11.10) in the following way: the
information in fls_currency gives a bound for how out of date the information in fls_currency gives a bound for how out of date the
data in a file system might typically get, while the age gives a data in a file system might typically get, while the value in fss_age
bound on how out of date that data actually is. Negative values gives a bound on how out of date that data actually is. Negative
imply that no information is available. A zero means that this data values imply that no information is available. A zero means that
is known to be current. A positive value means that this data is this data is known to be current. A positive value means that this
known to be no older than that number of seconds with respect to the data is known to be no older than that number of seconds with respect
ultimate data source. Using this value, the client may be able to to the ultimate data source. Using this value, the client may be
decide that a data copy is too old, so that it may search for a newer able to decide that a data copy is too old, so that it may search for
version to use. a newer version to use.
The version field provides a version identification, in the form of a The fss_version field provides a version identification, in the form
time value, such that successive versions always have later time of a time value, such that successive versions always have later time
values. When the file system type is anything other than values. When the fs_type is anything other than STATUS4_VERSIONED,
STATUS4_VERSIONED, the server may provide such a value but there is the server may provide such a value but there is no guarantee as to
no guarantee as to its validity and clients will not use it except to its validity and clients will not use it except to provide additional
provide additional information to add to 'source' and 'current'. information to add to fss_source and fss_current.
When the type is STATUS4_VERSIONED, servers SHOULD provide a value of When fss_type is STATUS4_VERSIONED, servers SHOULD provide a value of
version which progresses monotonically whenever any new version of version which progresses monotonically whenever any new version of
the data is established. This allows the client, if reliable image the data is established. This allows the client, if reliable image
progression is important to it, to fetch this attribute as part of progression is important to it, to fetch this attribute as part of
each COMPOUND where data or metadata from the file system is used. each COMPOUND where data or metadata from the file system is used.
When it is important to the client to make sure that only valid When it is important to the client to make sure that only valid
successor images are accepted, it must make sure that it does not successor images are accepted, it must make sure that it does not
read data or metadata from the file system without updating its sense read data or metadata from the file system without updating its sense
of the current state of the image, to avoid the possibility that the of the current state of the image, to avoid the possibility that the
fs_status which the client holds will be one for an earlier image, fs_status which the client holds will be one for an earlier image,
and so accept a new file system instance which is later than that but and so accept a new file system instance which is later than that but
still earlier than updated data read by the client. still earlier than updated data read by the client.
In order to do this reliably, it must do a GETATTR of fs_status that In order to do this reliably, it must do a GETATTR of the fs_status
follows any interrogation of data or metadata within the file system attribute that follows any interrogation of data or metadata within
in question. Often this is most conveniently done by appending such the file system in question. Often this is most conveniently done by
a GETATTR after all other operations that reference a given file appending such a GETATTR after all other operations that reference a
system. When errors occur between reading file system data and given file system. When errors occur between reading file system
performing such a GETATTR, care must be exercised to make sure that data and performing such a GETATTR, care must be exercised to make
the data in question is not used before obtaining the proper sure that the data in question is not used before obtaining the
fs_status value. In this connection, when an OPEN is done within proper fs_status value. In this connection, when an OPEN is done
such a versioned file system and the associated GETATTR of fs_status within such a versioned file system and the associated GETATTR of
is not successfully completed, the open file in question must not be fs_status is not successfully completed, the open file in question
accessed until that fs_status is fetched. must not be accessed until that fs_status is fetched.
The procedure above will ensure that before using any data from the The procedure above will ensure that before using any data from the
file system the client has in hand a newly-fetched current version of file system the client has in hand a newly-fetched current version of
the file system image. Multiple values for multiple requests in the file system image. Multiple values for multiple requests in
flight can be resolved by assembling them into the required partial flight can be resolved by assembling them into the required partial
order (and the elements should form a total order within it) and order (and the elements should form a total order within it) and
using the last. The client may then, when switching among file using the last. The client may then, when switching among file
system instances, decline to use an instance which is not of type system instances, decline to use an instance which does not have an
STATUS4_VERSIONED or whose version field is earlier than the last one fss_type of STATUS4_VERSIONED or whose fss_version field is earlier
obtained from the predecessor file system instance. than the last one obtained from the predecessor file system instance.
12. Parallel NFS (pNFS) 12. Parallel NFS (pNFS)
12.1. Introduction 12.1. Introduction
pNFS is an OPTIONAL feature within NFSv4.1; the pNFS feature set pNFS is an OPTIONAL feature within NFSv4.1; the pNFS feature set
allows direct client access to the storage devices containing file allows direct client access to the storage devices containing file
data. When file data for a single NFSv4 server is stored on multiple data. When file data for a single NFSv4 server is stored on multiple
and/or higher throughput storage devices (by comparison to the and/or higher throughput storage devices (by comparison to the
server's throughput capability), the result can be significantly server's throughput capability), the result can be significantly
 End of changes. 64 change blocks. 
217 lines changed or deleted 259 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/