Found wdiff, but it reported no recognisable version. Falling back to builtin diff colouring... Diff: draft-pre-ch-17.txt - draft-ietf-nfsv4-minorversion1-22.txt
 draft-pre-ch-17.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: October 3, 2008 Editors Expires: October 9, 2008 Editors
April 7, 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 33 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 October 3, 2008. This Internet-Draft will expire on October 9, 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 8, line 12 skipping to change at page 8, line 12
15.1.16. Obsoleted Errors . . . . . . . . . . . . . . . . . . 342 15.1.16. Obsoleted Errors . . . . . . . . . . . . . . . . . . 342
15.2. Operations and their valid errors . . . . . . . . . . . 343 15.2. Operations and their valid errors . . . . . . . . . . . 343
15.3. Callback operations and their valid errors . . . . . . . 359 15.3. Callback operations and their valid errors . . . . . . . 359
15.4. Errors and the operations that use them . . . . . . . . 361 15.4. Errors and the operations that use them . . . . . . . . 361
16. NFSv4.1 Procedures . . . . . . . . . . . . . . . . . . . . . 375 16. NFSv4.1 Procedures . . . . . . . . . . . . . . . . . . . . . 375
16.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 375 16.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 375
16.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 376 16.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 376
17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . 387 17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . 387
18. NFSv4.1 Operations . . . . . . . . . . . . . . . . . . . . . 390 18. NFSv4.1 Operations . . . . . . . . . . . . . . . . . . . . . 390
18.1. Operation 3: ACCESS - Check Access Rights . . . . . . . 390 18.1. Operation 3: ACCESS - Check Access Rights . . . . . . . 390
18.2. Operation 4: CLOSE - Close File . . . . . . . . . . . . 393 18.2. Operation 4: CLOSE - Close File . . . . . . . . . . . . 396
18.3. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 394 18.3. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 397
18.4. Operation 6: CREATE - Create a Non-Regular File Object . 397 18.4. Operation 6: CREATE - Create a Non-Regular File Object . 400
18.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 18.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 400 Recovery . . . . . . . . . . . . . . . . . . . . . . . . 403
18.6. Operation 8: DELEGRETURN - Return Delegation . . . . . . 401 18.6. Operation 8: DELEGRETURN - Return Delegation . . . . . . 404
18.7. Operation 9: GETATTR - Get Attributes . . . . . . . . . 401 18.7. Operation 9: GETATTR - Get Attributes . . . . . . . . . 404
18.8. Operation 10: GETFH - Get Current Filehandle . . . . . . 403 18.8. Operation 10: GETFH - Get Current Filehandle . . . . . . 406
18.9. Operation 11: LINK - Create Link to a File . . . . . . . 404 18.9. Operation 11: LINK - Create Link to a File . . . . . . . 407
18.10. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 406 18.10. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 410
18.11. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 410 18.11. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 413
18.12. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 412 18.12. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 415
18.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 413 18.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 416
18.14. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 415 18.14. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 418
18.15. Operation 17: NVERIFY - Verify Difference in 18.15. Operation 17: NVERIFY - Verify Difference in
Attributes . . . . . . . . . . . . . . . . . . . . . . . 416 Attributes . . . . . . . . . . . . . . . . . . . . . . . 419
18.16. Operation 18: OPEN - Open a Regular File . . . . . . . . 417 18.16. Operation 18: OPEN - Open a Regular File . . . . . . . . 420
18.17. Operation 19: OPENATTR - Open Named Attribute 18.17. Operation 19: OPENATTR - Open Named Attribute
Directory . . . . . . . . . . . . . . . . . . . . . . . 436 Directory . . . . . . . . . . . . . . . . . . . . . . . 439
18.18. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 437 18.18. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 440
18.19. Operation 22: PUTFH - Set Current Filehandle . . . . . . 439 18.19. Operation 22: PUTFH - Set Current Filehandle . . . . . . 442
18.20. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 439 18.20. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 442
18.21. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 441 18.21. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 444
18.22. Operation 25: READ - Read from File . . . . . . . . . . 442 18.22. Operation 25: READ - Read from File . . . . . . . . . . 445
18.23. Operation 26: READDIR - Read Directory . . . . . . . . . 444 18.23. Operation 26: READDIR - Read Directory . . . . . . . . . 447
18.24. Operation 27: READLINK - Read Symbolic Link . . . . . . 448 18.24. Operation 27: READLINK - Read Symbolic Link . . . . . . 451
18.25. Operation 28: REMOVE - Remove File System Object . . . . 449 18.25. Operation 28: REMOVE - Remove File System Object . . . . 452
18.26. Operation 29: RENAME - Rename Directory Entry . . . . . 451 18.26. Operation 29: RENAME - Rename Directory Entry . . . . . 454
18.27. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 455 18.27. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 458
18.28. Operation 32: SAVEFH - Save Current Filehandle . . . . . 456 18.28. Operation 32: SAVEFH - Save Current Filehandle . . . . . 459
18.29. Operation 33: SECINFO - Obtain Available Security . . . 457 18.29. Operation 33: SECINFO - Obtain Available Security . . . 460
18.30. Operation 34: SETATTR - Set Attributes . . . . . . . . . 460 18.30. Operation 34: SETATTR - Set Attributes . . . . . . . . . 463
18.31. Operation 37: VERIFY - Verify Same Attributes . . . . . 462 18.31. Operation 37: VERIFY - Verify Same Attributes . . . . . 465
18.32. Operation 38: WRITE - Write to File . . . . . . . . . . 463 18.32. Operation 38: WRITE - Write to File . . . . . . . . . . 466
18.33. Operation 40: BACKCHANNEL_CTL - Backchannel control . . 468 18.33. Operation 40: BACKCHANNEL_CTL - Backchannel control . . 471
18.34. Operation 41: BIND_CONN_TO_SESSION . . . . . . . . . . . 469 18.34. Operation 41: BIND_CONN_TO_SESSION . . . . . . . . . . . 472
18.35. Operation 42: EXCHANGE_ID - Instantiate Client ID . . . 472 18.35. Operation 42: EXCHANGE_ID - Instantiate Client ID . . . 475
18.36. Operation 43: CREATE_SESSION - Create New Session and 18.36. Operation 43: CREATE_SESSION - Create New Session and
Confirm Client ID . . . . . . . . . . . . . . . . . . . 488 Confirm Client ID . . . . . . . . . . . . . . . . . . . 491
18.37. Operation 44: DESTROY_SESSION - Destroy existing 18.37. Operation 44: DESTROY_SESSION - Destroy existing
session . . . . . . . . . . . . . . . . . . . . . . . . 498 session . . . . . . . . . . . . . . . . . . . . . . . . 501
18.38. Operation 45: FREE_STATEID - Free stateid with no 18.38. Operation 45: FREE_STATEID - Free stateid with no
locks . . . . . . . . . . . . . . . . . . . . . . . . . 500 locks . . . . . . . . . . . . . . . . . . . . . . . . . 503
18.39. Operation 46: GET_DIR_DELEGATION - Get a directory 18.39. Operation 46: GET_DIR_DELEGATION - Get a directory
delegation . . . . . . . . . . . . . . . . . . . . . . . 501 delegation . . . . . . . . . . . . . . . . . . . . . . . 504
18.40. Operation 47: GETDEVICEINFO - Get Device Information . . 505 18.40. Operation 47: GETDEVICEINFO - Get Device Information . . 508
18.41. Operation 48: GETDEVICELIST - Get All Device Mappings 18.41. Operation 48: GETDEVICELIST - Get All Device Mappings
for a File System . . . . . . . . . . . . . . . . . . . 507 for a File System . . . . . . . . . . . . . . . . . . . 510
18.42. Operation 49: LAYOUTCOMMIT - Commit writes made using 18.42. Operation 49: LAYOUTCOMMIT - Commit writes made using
a layout . . . . . . . . . . . . . . . . . . . . . . . . 509 a layout . . . . . . . . . . . . . . . . . . . . . . . . 512
18.43. Operation 50: LAYOUTGET - Get Layout Information . . . . 512 18.43. Operation 50: LAYOUTGET - Get Layout Information . . . . 515
18.44. Operation 51: LAYOUTRETURN - Release Layout 18.44. Operation 51: LAYOUTRETURN - Release Layout
Information . . . . . . . . . . . . . . . . . . . . . . 516 Information . . . . . . . . . . . . . . . . . . . . . . 519
18.45. Operation 52: SECINFO_NO_NAME - Get Security on 18.45. Operation 52: SECINFO_NO_NAME - Get Security on
Unnamed Object . . . . . . . . . . . . . . . . . . . . . 521 Unnamed Object . . . . . . . . . . . . . . . . . . . . . 524
18.46. Operation 53: SEQUENCE - Supply per-procedure 18.46. Operation 53: SEQUENCE - Supply per-procedure
sequencing and control . . . . . . . . . . . . . . . . . 522 sequencing and control . . . . . . . . . . . . . . . . . 525
18.47. Operation 54: SET_SSV - Update SSV for a Client ID . . . 528 18.47. Operation 54: SET_SSV - Update SSV for a Client ID . . . 531
18.48. Operation 55: TEST_STATEID - Test stateids for 18.48. Operation 55: TEST_STATEID - Test stateids for
validity . . . . . . . . . . . . . . . . . . . . . . . . 530 validity . . . . . . . . . . . . . . . . . . . . . . . . 533
18.49. Operation 56: WANT_DELEGATION - Request Delegation . . . 532 18.49. Operation 56: WANT_DELEGATION - Request Delegation . . . 535
18.50. Operation 57: DESTROY_CLIENTID - Destroy existing 18.50. Operation 57: DESTROY_CLIENTID - Destroy existing
client ID . . . . . . . . . . . . . . . . . . . . . . . 536 client ID . . . . . . . . . . . . . . . . . . . . . . . 539
18.51. Operation 58: RECLAIM_COMPLETE - Indicates Reclaims 18.51. Operation 58: RECLAIM_COMPLETE - Indicates Reclaims
Finished . . . . . . . . . . . . . . . . . . . . . . . . 536 Finished . . . . . . . . . . . . . . . . . . . . . . . . 539
18.52. Operation 10044: ILLEGAL - Illegal operation . . . . . . 539 18.52. Operation 10044: ILLEGAL - Illegal operation . . . . . . 542
19. NFSv4.1 Callback Procedures . . . . . . . . . . . . . . . . . 539 19. NFSv4.1 Callback Procedures . . . . . . . . . . . . . . . . . 542
19.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 540 19.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 543
19.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 540 19.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 543
20. NFSv4.1 Callback Operations . . . . . . . . . . . . . . . . . 544 20. NFSv4.1 Callback Operations . . . . . . . . . . . . . . . . . 547
20.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . . . 544 20.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . . . 547
20.2. Operation 4: CB_RECALL - Recall an Open Delegation . . . 545 20.2. Operation 4: CB_RECALL - Recall an Open Delegation . . . 548
20.3. Operation 5: CB_LAYOUTRECALL - Recall Layout from 20.3. Operation 5: CB_LAYOUTRECALL - Recall Layout from
Client . . . . . . . . . . . . . . . . . . . . . . . . . 546 Client . . . . . . . . . . . . . . . . . . . . . . . . . 549
20.4. Operation 6: CB_NOTIFY - Notify directory changes . . . 550 20.4. Operation 6: CB_NOTIFY - Notify directory changes . . . 553
20.5. Operation 7: CB_PUSH_DELEG - Offer Delegation to 20.5. Operation 7: CB_PUSH_DELEG - Offer Delegation to
Client . . . . . . . . . . . . . . . . . . . . . . . . . 554 Client . . . . . . . . . . . . . . . . . . . . . . . . . 557
20.6. Operation 8: CB_RECALL_ANY - Keep any N delegations . . 555 20.6. Operation 8: CB_RECALL_ANY - Keep any N delegations . . 558
20.7. Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal 20.7. Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal
Resources for Recallable Objects . . . . . . . . . . . . 557 Resources for Recallable Objects . . . . . . . . . . . . 560
20.8. Operation 10: CB_RECALL_SLOT - change flow control 20.8. Operation 10: CB_RECALL_SLOT - change flow control
limits . . . . . . . . . . . . . . . . . . . . . . . . . 558 limits . . . . . . . . . . . . . . . . . . . . . . . . . 561
20.9. Operation 11: CB_SEQUENCE - Supply backchannel 20.9. Operation 11: CB_SEQUENCE - Supply backchannel
sequencing and control . . . . . . . . . . . . . . . . . 559 sequencing and control . . . . . . . . . . . . . . . . . 562
20.10. Operation 12: CB_WANTS_CANCELLED - Cancel Pending 20.10. Operation 12: CB_WANTS_CANCELLED - Cancel Pending
Delegation Wants . . . . . . . . . . . . . . . . . . . . 561 Delegation Wants . . . . . . . . . . . . . . . . . . . . 564
20.11. Operation 13: CB_NOTIFY_LOCK - Notify of possible 20.11. Operation 13: CB_NOTIFY_LOCK - Notify of possible
lock availability . . . . . . . . . . . . . . . . . . . 562 lock availability . . . . . . . . . . . . . . . . . . . 565
20.12. Operation 14: CB_NOTIFY_DEVICEID - Notify device ID 20.12. Operation 14: CB_NOTIFY_DEVICEID - Notify device ID
changes . . . . . . . . . . . . . . . . . . . . . . . . 564 changes . . . . . . . . . . . . . . . . . . . . . . . . 567
20.13. Operation 10044: CB_ILLEGAL - Illegal Callback 20.13. Operation 10044: CB_ILLEGAL - Illegal Callback
Operation . . . . . . . . . . . . . . . . . . . . . . . 566 Operation . . . . . . . . . . . . . . . . . . . . . . . 569
21. Security Considerations . . . . . . . . . . . . . . . . . . . 566 21. Security Considerations . . . . . . . . . . . . . . . . . . . 569
22. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 568 22. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 571
22.1. Named Attribute Definitions . . . . . . . . . . . . . . 568 22.1. Named Attribute Definitions . . . . . . . . . . . . . . 571
22.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 568 22.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 571
22.3. Defining New Notifications . . . . . . . . . . . . . . . 569 22.3. Defining New Notifications . . . . . . . . . . . . . . . 572
22.4. Defining New Layout Types . . . . . . . . . . . . . . . 569 22.4. Defining New Layout Types . . . . . . . . . . . . . . . 572
22.5. Path Variable Definitions . . . . . . . . . . . . . . . 571 22.5. Path Variable Definitions . . . . . . . . . . . . . . . 574
22.5.1. Path Variable Values . . . . . . . . . . . . . . . . 571 22.5.1. Path Variable Values . . . . . . . . . . . . . . . . 574
22.5.2. Path Variable Names . . . . . . . . . . . . . . . . 571 22.5.2. Path Variable Names . . . . . . . . . . . . . . . . 574
23. References . . . . . . . . . . . . . . . . . . . . . . . . . 571 23. References . . . . . . . . . . . . . . . . . . . . . . . . . 574
23.1. Normative References . . . . . . . . . . . . . . . . . . 571 23.1. Normative References . . . . . . . . . . . . . . . . . . 574
23.2. Informative References . . . . . . . . . . . . . . . . . 573 23.2. Informative References . . . . . . . . . . . . . . . . . 576
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 574 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 578
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 576 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 580
Intellectual Property and Copyright Statements . . . . . . . . . 578 Intellectual Property and Copyright Statements . . . . . . . . . 581
1. Introduction 1. Introduction
1.1. The NFS Version 4 Minor Version 1 Protocol 1.1. The NFS Version 4 Minor Version 1 Protocol
The NFS version 4 minor version 1 (NFSv4.1) protocol is the second The NFS version 4 minor version 1 (NFSv4.1) protocol is the second
minor version of the NFS version 4 (NFSv4) protocol. The first minor minor version of the NFS version 4 (NFSv4) protocol. The first minor
version, NFSv4.0 is described in [21]. It generally follows the version, NFSv4.0 is described in [21]. It generally follows the
guidelines for minor versioning model listed in Section 10 of RFC guidelines for minor versioning model listed in Section 10 of RFC
3530. However, it diverges from guidelines 11 ("a client and server 3530. However, it diverges from guidelines 11 ("a client and server
skipping to change at page 149, line 23 skipping to change at page 149, line 23
The server may assign stateids independently for different clients. The server may assign stateids independently for different clients.
A stateid with the same bit pattern for one client may designate an A stateid with the same bit pattern for one client may designate an
entirely different set of locks for a different client. The stateid entirely different set of locks for a different client. The stateid
is always interpreted with respect to the client ID associated with is always interpreted with respect to the client ID associated with
the current session. Stateids apply to all sessions associated with the current session. Stateids apply to all sessions associated with
the given client ID and the client may use a stateid obtained from the given client ID and the client may use a stateid obtained from
one session on another session associated with the same client ID. one session on another session associated with the same client ID.
8.2.1. Stateid Types 8.2.1. Stateid Types
With the exception of special stateids, to be discussed later, each With the exception of special stateids (see Section 8.2.3), each
stateid represents locking objects of one of a set of types defined stateid represents locking objects of one of a set of types defined
by the NFSv4.1 protocol. Note that in all these cases, where we by the NFSv4.1 protocol. Note that in all these cases, where we
speak of guarantee, it is understood there are situations such as a speak of guarantee, it is understood there are situations such as a
client restart, or lock revocation, that allow the guarantee to be client restart, or lock revocation, that allow the guarantee to be
voided. voided.
o Stateids may represent opens of files. o Stateids may represent opens of files.
Each stateid in this case represents the open state for a given Each stateid in this case represents the open state for a given
client ID/open-owner/filehandle triple. Such stateids are subject client ID/open-owner/filehandle triple. Such stateids are subject
skipping to change at page 150, line 29 skipping to change at page 150, line 29
A stateid represents the set of all layouts held by a particular A stateid represents the set of all layouts held by a particular
client for a particular filehandle with a given layout type. The client for a particular filehandle with a given layout type. The
seqid is updated as the layouts of that set changes with layout seqid is updated as the layouts of that set changes with layout
stateid changing operations such as LAYOUTGET and LAYOUTRETURN. stateid changing operations such as LAYOUTGET and LAYOUTRETURN.
8.2.2. Stateid Structure 8.2.2. Stateid Structure
Stateids are divided into two fields, a 96-bit "other" field Stateids are divided into two fields, a 96-bit "other" field
identifying the specific set of locks and a 32-bit "seqid" sequence identifying the specific set of locks and a 32-bit "seqid" sequence
value. Except in the case of special stateids, to be discussed value. Except in the case of special stateids (see Section 8.2.3), a
below, a particular value of the "other" field denotes a set of locks particular value of the "other" field denotes a set of locks of the
of the same type (for example byte-range locks, opens, delegations, same type (for example byte-range locks, opens, delegations, or
or layouts), for a specific file or directory, and sharing the same layouts), for a specific file or directory, and sharing the same
ownership characteristics. The seqid designates a specific instance ownership characteristics. The seqid designates a specific instance
of such a set of locks, and is incremented to indicate changes in of such a set of locks, and is incremented to indicate changes in
such a set of locks, either by the addition or deletion of locks from such a set of locks, either by the addition or deletion of locks from
the set, a change in the byte-range they apply to, or an upgrade or the set, a change in the byte-range they apply to, or an upgrade or
downgrade in the type of one or more locks. downgrade in the type of one or more locks.
When such a set of locks is first created the server returns a When such a set of locks is first created the server returns a
stateid with seqid value of one. On subsequent operations which stateid with seqid value of one. On subsequent operations which
modify the set of locks the server is required to increment the seqid modify the set of locks the server is required to increment the seqid
field by one (1) whenever it returns a stateid for the same state- field by one (1) whenever it returns a stateid for the same state-
skipping to change at page 154, line 18 skipping to change at page 154, line 18
o The last "seqid" value returned corresponding to the current o The last "seqid" value returned corresponding to the current
"other" value. "other" value.
o An indication of the current status of the locks associated with o An indication of the current status of the locks associated with
this stateid. In particular, whether these have been revoked and this stateid. In particular, whether these have been revoked and
if so, for what reason. if so, for what reason.
With this information, an incoming stateid can be validated and the With this information, an incoming stateid can be validated and the
appropriate error returned when necessary. Special and non-special appropriate error returned when necessary. Special and non-special
stateids are handled separately. (See Section 8.2.3 for a discussion stateids are handled separately. (See Section 8.2.3 for a discussion
of special stateids). of special stateids.)
Note that stateids are implicitly qualified by the current client ID, Note that stateids are implicitly qualified by the current client ID,
as derived from the client ID associated with the current session. as derived from the client ID associated with the current session.
Note however, that the semantics of the session will prevent stateids Note however, that the semantics of the session will prevent stateids
associated with a previous client or server instance from being associated with a previous client or server instance from being
analyzed by this procedure. analyzed by this procedure.
If server restart has resulted in an invalid client ID or a sessionid If server restart has resulted in an invalid client ID or a sessionid
which is invalid, SEQUENCE will return an error and the operation which is invalid, SEQUENCE will return an error and the operation
that takes a stateid as an argument will never be processed. that takes a stateid as an argument will never be processed.
skipping to change at page 387, line 32 skipping to change at page 387, line 32
+------------------------------+------------------------------------+ +------------------------------+------------------------------------+
Table 15 Table 15
17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL 17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL
The following tables summarize the operations of the NFSv4.1 protocol The following tables summarize the operations of the NFSv4.1 protocol
and the corresponding designation of REQUIRED, RECOMMENDED, OPTIONAL and the corresponding designation of REQUIRED, RECOMMENDED, OPTIONAL
to implement or MUST NOT implement. The designation of MUST NOT to implement or MUST NOT implement. The designation of MUST NOT
implement is reserved for those operations that were defined in implement is reserved for those operations that were defined in
NFSv4.0 and they MUST NOT be implemented in NFSv4.1. These NFSv4.0 and MUST NOT be implemented in NFSv4.1.
operations are limited to those replaced by the Sessions
functionality of NFSv4.1.
For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation
is for the server implementation. The client is generally required for operations sent by the client is for the server implementation.
to implement the operations needed for the operating environment for The client is generally required to implement the operations needed
which it serves. For example, a read-only NFSv4.1 client would have for the operating environment for which it serves. For example, a
no need to implement the WRITE operation and is not required to do read-only NFSv4.1 client would have no need to implement the WRITE
so. operation and is not required to do so.
The REQUIRED or OPTIONAL designation for callback operations sent by
the server is for both the client and server. Generally, the client
has the option of creating the backchannel and sending the operations
on the fore channel that will be a catalyst for the server sending
callback operations. A partial exception is CB_RECALL_SLOT; the only
way the client can avoid supporting this operation is by not creating
a backchannel.
Since this is a summary of the operations and their designation, Since this is a summary of the operations and their designation,
there are subtleties that are not presented here. Therefore, if there are subtleties that are not presented here. Therefore, if
there is a question of the requirements of implementation, the there is a question of the requirements of implementation, the
operation descriptions themselves must be consulted along with other operation descriptions themselves must be consulted along with other
relevant explanatory text within this specification. relevant explanatory text within this specification.
The abbreviations used in the second and third columns of the table The abbreviations used in the second and third columns of the table
are defined as follows. are defined as follows.
skipping to change at page 391, line 33 skipping to change at page 391, line 46
credentials in the RPC request, has with respect to the file system credentials in the RPC request, has with respect to the file system
object specified by the current filehandle. The client encodes the object specified by the current filehandle. The client encodes the
set of access rights that are to be checked in the bit mask "access". set of access rights that are to be checked in the bit mask "access".
The server checks the permissions encoded in the bit mask. If a The server checks the permissions encoded in the bit mask. If a
status of NFS4_OK is returned, two bit masks are included in the status of NFS4_OK is returned, two bit masks are included in the
response. The first, "supported", represents the access rights for response. The first, "supported", represents the access rights for
which the server can verify reliably. The second, "access", which the server can verify reliably. The second, "access",
represents the access rights available to the user for the filehandle represents the access rights available to the user for the filehandle
provided. On success, the current filehandle retains its value. provided. On success, the current filehandle retains its value.
Note that the supported field will contain only as many values as was Note that the reply's supported and access fields MUST NOT contain
originally sent in the arguments. For example, if the client sends more values than originally sent in the requests access field. For
an ACCESS operation with only the ACCESS4_READ value set and the example, if the client sends an ACCESS operation with only the
server supports this value, the server will return only ACCESS4_READ ACCESS4_READ value set and the server supports this value, the server
even if it could have reliably checked other values. can set only ACCESS4_READ in the supported field even if it could
have reliably checked other values.
The reply's access field MUST NOT contain more values than in the
supported field.
The results of this operation are necessarily advisory in nature. A The results of this operation are necessarily advisory in nature. A
return status of NFS4_OK and the appropriate bit set in the bit mask return status of NFS4_OK and the appropriate bit set in the bit mask
does not imply that such access will be allowed to the file system does not imply that such access will be allowed to the file system
object in the future. This is because access rights can be revoked object in the future. This is because access rights can be revoked
by the server at any time. by the server at any time.
The following access permissions may be requested: The following access permissions may be requested:
ACCESS4_READ Read data from file or read a directory. ACCESS4_READ Read data from file or read a directory.
skipping to change at page 392, line 17 skipping to change at page 392, line 30
ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- ACCESS4_LOOKUP Look up a name in a directory (no meaning for non-
directory objects). directory objects).
ACCESS4_MODIFY Rewrite existing file data or modify existing ACCESS4_MODIFY Rewrite existing file data or modify existing
directory entries. directory entries.
ACCESS4_EXTEND Write new data or add directory entries. ACCESS4_EXTEND Write new data or add directory entries.
ACCESS4_DELETE Delete an existing directory entry. ACCESS4_DELETE Delete an existing directory entry.
ACCESS4_EXECUTE Execute file (no meaning for a directory). ACCESS4_EXECUTE Execute a regular file (no meaning for a directory).
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
ACCESS4_EXECUTE is a challenging semantic to implement because NFS
provides remote file access, not remote execution. This leads to the
following:
o Whether a regular file is executable or not ought to be the
responsibility of the NFS client and not the server. And yet the
ACCESS operation is specified to seemingly require a server to own
that responsibility.
o When a client executes a regular file, it has to read the file
from the server. Strictly speaking, the server should not allow
the client to read a file being executed unless the user has read
permissions on the file. Requiring users and administers to set
read permissions on executable files in order to access them over
NFS is not going to be acceptable some people. Historically, NFS
servers have allowed a user to READ a file if the user has execute
access to the file.
As a practical example, the UNIX specification [41] states that an
implementation claiming conformance to UNIX may indicate in the
access() programming interface's result that a privileged user has
execute rights, even if no execute permission bits are set on the
regular file's attributes. It is possible to claim conformance to
the UNIX specification and instead not indicate execute rights in
that situation, which is true for some operating enviroments.
Suppose the operating environments of the client and server are
implementing the access() semantics for privileged users differently,
and the ACCESS operation implementations of the client and server
follow their respective access() semantics. This can cause undesired
behavior:
o Suppose the client's access() interface returns X_OK if the user
is privileged, no execute permission bits are set on the regular
file's attribute, and the server's access() interface does not
return X_OK in that situation. Then the client will be unable to
execute files stored on the NFS server that could be executed if
stored on a non-NFS file system.
o Suppose the client's access() interface does not return X_OK if
the user is privileged, and no execute permission bits are set on
the regular file's attribute, and the server's access() interface
does return X_OK in that situation. Then:
* The client will be able to execute files stored on the NFS
server that could be executed if stored on a non-NFS file
system, unless the client's execution subsystem also checks for
execute permission bits.
* Even if the execution subsystem is checking for execute
permission bits, there are more potential issues. E.g. suppose
the client is invoking access() to build a "path search table"
of all executable files in the user's "search path", where the
path is a list of directories each containing executable files.
Suppose there are two files each in separate directories of the
search path, such that files have the same component name. In
the first directory the file has no execute permission bits
set, and in the second directory the file has execute bits set.
The path search table will indicate that the first directory
has the executable file, but the execute subsystem will fail to
execute it. The command shell might fail to try the second
file in the second directory. And even if it did, this is a
potential performance issue. Clearly the desired outcome for
the client is for the path search table to not contain the
first file.
To deal the problems described above, the smart client, stupid server
principle is used. The client owns overall responsibility for
determining execute access, and relies on the server to parse the
execution permissions within the file's mode, acl, and dacl
attributes. The rules for the client and server follow:
o If the client is sending ACCESS in order to determine if the user
can read the file, the client SHOULD set ACCESS4_READ in the
request's access field.
o If the client's operating environment only grants execution to the
user if the user has execute access according to the execute
permissions in the mode, acl, and dacl attributes, then if the
client wants to determine execute access, the client SHOULD send
an ACCESS request with ACCESS4_EXECUTE bit set in the request's
access field.
o If the client's operating environment grants execution to the user
even if the user does not have execute access according to the
execute permissions in the mode, acl, and dacl attributes, then if
the client wants to determine execute access, it SHOULD send an
ACCESS request with both the ACCESS4_EXECUTE and ACCESS4_READ bits
set the request's access field. This way, if any read or execute
permission grants the user read or execute access (or if the
server interprets the user as privileged), as indicated by the
presence of ACCESS4_EXECUTE and/or ACCESS4_READ in the reply's
access field, the client will be able to grant the user execute
access to the file.
o If the server supports execute permission bits, it MUST check just
the execute permissions in the mode, acl, and dacl attributes when
it receives an ACCESS request with ACCESS4_EXECUTE set the access
field. The server MUST NOT also examine read permission bits when
determining whether the reply will have ACCESS4_EXECUTE set in the
access field or not. Even if the server's operating environment
would grant execute access to the user (e.g., the user is
privileged), the server MUST NOT reply with ACCESS4_EXECUTE set in
reply's access field, unless there is at least one execute
permission bit set in the mode, acl, or dacl attributes. In the
case of acl and dacl, the "one execute permission bit" MUST be an
ACE4_EXECUTE bit set in an ALLOW ACE.
o If the server does not support execute permission bits, it MUST
NOT set ACCESS4_EXECUTE in the reply's supported and access
fields. If the client set ACCESS4_EXECUTE in the ACCESS request's
access field, and ACCESS4_EXECUTE is not set in the reply's
supported field, then the client will have to send an ACCESS
request with the ACCESS4_READ bit set in the request's access
field.
o If the server supports read permission bits, it MUST only check
for read permissions in the mode, acl, and dacl attributes when it
receives an ACCESS request with ACCESS4_READ set the access field.
The server MUST NOT also examine execute permission bits when
determining whether the reply will have ACCESS4_READ set in the
access field or not.
Note that if the ACCESS reply has ACCESS4_READ or ACCESS_EXECUTE set,
then the user also has permissions to OPEN (Section 18.16) or READ
(Section 18.22) the file. I.e., if client sends an ACCESS request
with the ACCESS4_READ and ACCESS_EXECUTE set in the access field (or
two separate requests, one with ACCESS4_READ set, and the other with
ACCESS4_EXECUTE set), and the reply has just ACCESS4_EXECUTE set in
the access field (or just one reply has ACCESS4_EXECUTE set), then
the user has authorization to OPEN or READ the file.
18.1.4. IMPLEMENTATION 18.1.4. IMPLEMENTATION
In general, it is not sufficient for the client to attempt to deduce In general, it is not sufficient for the client to attempt to deduce
access permissions by inspecting the uid, gid, and mode fields in the access permissions by inspecting the uid, gid, and mode fields in the
file attributes or by attempting to interpret the contents of the ACL file attributes or by attempting to interpret the contents of the ACL
attribute. This is because the server may perform uid or gid mapping attribute. This is because the server may perform uid or gid mapping
or enforce additional access control restrictions. It is also or enforce additional access control restrictions. It is also
possible that the server may not be in the same ID space as the possible that the server may not be in the same ID space as the
client. In these cases (and perhaps others), the client can not client. In these cases (and perhaps others), the client can not
reliably perform an access check with only current file attributes. reliably perform an access check with only current file attributes.
skipping to change at page 392, line 42 skipping to change at page 395, line 42
In the NFSv2 protocol, the only reliable way to determine whether an In the NFSv2 protocol, the only reliable way to determine whether an
operation was allowed was to try it and see if it succeeded or operation was allowed was to try it and see if it succeeded or
failed. Using the ACCESS operation in the NFSv4.1 protocol, the failed. Using the ACCESS operation in the NFSv4.1 protocol, the
client can ask the server to indicate whether or not one or more client can ask the server to indicate whether or not one or more
classes of operations are permitted. The ACCESS operation is classes of operations are permitted. The ACCESS operation is
provided to allow clients to check before doing a series of provided to allow clients to check before doing a series of
operations which will result in an access failure. The OPEN operations which will result in an access failure. The OPEN
operation provides a point where the server can verify access to the operation provides a point where the server can verify access to the
file object and method to return that information to the client. The file object and method to return that information to the client. The
ACCESS operation is still useful for directory operations or for use ACCESS operation is still useful for directory operations or for use
in the case the UNIX API "access" is used on the client. in the case the UNIX interface access() is used on the client.
The information returned by the server in response to an ACCESS call The information returned by the server in response to an ACCESS call
is not permanent. It was correct at the exact time that the server is not permanent. It was correct at the exact time that the server
performed the checks, but not necessarily afterwards. The server can performed the checks, but not necessarily afterwards. The server can
revoke access permission at any time. revoke access permission at any time.
The client should use the effective credentials of the user to build The client should use the effective credentials of the user to build
the authentication information in the ACCESS request used to the authentication information in the ACCESS request used to
determine access rights. It is the effective user and group determine access rights. It is the effective user and group
credentials that are used in subsequent read and write operations. credentials that are used in subsequent read and write operations.
skipping to change at page 394, line 25 skipping to change at page 397, line 25
18.2.4. IMPLEMENTATION 18.2.4. IMPLEMENTATION
Even though CLOSE returns a stateid, this stateid is not useful to Even though CLOSE returns a stateid, this stateid is not useful to
the client and should be treated as deprecated. CLOSE "shuts down" the client and should be treated as deprecated. CLOSE "shuts down"
the state associated with all OPENs for the file by a single open- the state associated with all OPENs for the file by a single open-
owner. As noted above, CLOSE will either release all file locking owner. As noted above, CLOSE will either release all file locking
state or return an error. Therefore, the stateid returned by CLOSE state or return an error. Therefore, the stateid returned by CLOSE
is not useful for operations that follow. To help find any uses of is not useful for operations that follow. To help find any uses of
this stateid by clients, the server SHOULD return the invalid special this stateid by clients, the server SHOULD return the invalid special
stated (the "other" value is zero and the "seqid" field is stated (the "other" value is zero and the "seqid" field is
NFS4_MAXFILELEN). NFS4_UINT32_MAX, see Section 8.2.3).
A CLOSE operation may make delegations grantable where they were not A CLOSE operation may make delegations grantable where they were not
previously. Servers may choose to respond immediately if there are previously. Servers may choose to respond immediately if there are
pending delegation want requests or may respond to the situation at a pending delegation want requests or may respond to the situation at a
later time. later time.
18.3. Operation 5: COMMIT - Commit Cached Data 18.3. Operation 5: COMMIT - Commit Cached Data
18.3.1. ARGUMENTS 18.3.1. ARGUMENTS
skipping to change at page 395, line 20 skipping to change at page 398, line 20
union COMMIT4res switch (nfsstat4 status) { union COMMIT4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
COMMIT4resok resok4; COMMIT4resok resok4;
default: default:
void; void;
}; };
18.3.3. DESCRIPTION 18.3.3. DESCRIPTION
The COMMIT operation forces or flushes data to stable storage for the The COMMIT operation forces or flushes uncommitted, modified data to
file specified by the current filehandle. The flushed data is that stable storage for the file specified by the current filehandle. The
which was previously written with a WRITE operation which had the flushed data is that which was previously written with a WRITE
stable field set to UNSTABLE4. operation which had the stable field set to UNSTABLE4.
The offset specifies the position within the file where the flush is The offset specifies the position within the file where the flush is
to begin. An offset value of 0 (zero) means to flush data starting to begin. An offset value of 0 (zero) means to flush data starting
at the beginning of the file. The count specifies the number of at the beginning of the file. The count specifies the number of
bytes of data to flush. If count is 0 (zero), a flush from offset to bytes of data to flush. If count is 0 (zero), a flush from offset to
the end of the file is done. the end of the file is done.
The server returns a write verifier upon successful completion of the The server returns a write verifier upon successful completion of the
COMMIT. The write verifier is used by the client to determine if the COMMIT. The write verifier is used by the client to determine if the
server has restarted between the initial WRITE(s) and the COMMIT. server has restarted between the initial WRITE(s) and the COMMIT.
skipping to change at page 396, line 17 skipping to change at page 399, line 17
unless there has been an unexpected error. unless there has been an unexpected error.
COMMIT differs from fsync(2) in that it is possible for the client to COMMIT differs from fsync(2) in that it is possible for the client to
flush a range of the file (most likely triggered by a buffer- flush a range of the file (most likely triggered by a buffer-
reclamation scheme on the client before file has been completely reclamation scheme on the client before file has been completely
written). written).
The server implementation of COMMIT is reasonably simple. If the The server implementation of COMMIT is reasonably simple. If the
server receives a full file COMMIT request, that is starting at server receives a full file COMMIT request, that is starting at
offset 0 and count 0, it should do the equivalent of fsync()'ing the offset 0 and count 0, it should do the equivalent of fsync()'ing the
file. Otherwise, it should arrange to have the cached data in the file. Otherwise, it should arrange to have the modified data in the
range specified by offset and count to be flushed to stable storage. range specified by offset and count to be flushed to stable storage.
In both cases, any metadata associated with the file must be flushed In both cases, any metadata associated with the file must be flushed
to stable storage before returning. It is not an error for there to to stable storage before returning. It is not an error for there to
be nothing to flush on the server. This means that the data and be nothing to flush on the server. This means that the data and
metadata that needed to be flushed have already been flushed or lost metadata that needed to be flushed have already been flushed or lost
during the last server failure. during the last server failure.
The client implementation of COMMIT is a little more complex. There The client implementation of COMMIT is a little more complex. There
are two reasons for wanting to commit a client buffer to stable are two reasons for wanting to commit a client buffer to stable
storage. The first is that the client wants to reuse a buffer. In storage. The first is that the client wants to reuse a buffer. In
this case, the offset and count of the buffer are sent to the server this case, the offset and count of the buffer are sent to the server
in the COMMIT request. The server then flushes any cached data based in the COMMIT request. The server then flushes any modified data
on the offset and count, and flushes any metadata associated with the based on the offset and count, and flushes any modified metadata
file. It then returns the status of the flush and the write associated with the file. It then returns the status of the flush
verifier. The other reason for the client to generate a COMMIT is and the write verifier. The other reason for the client to generate
for a full file flush, such as may be done at close. In this case, a COMMIT is for a full file flush, such as may be done at close. In
the client would gather all of the buffers for this file that contain this case, the client would gather all of the buffers for this file
uncommitted data, do the COMMIT operation with an offset of 0 and that contain uncommitted data, do the COMMIT operation with an offset
count of 0, and then free all of those buffers. Any other dirty of 0 and count of 0, and then free all of those buffers. Any other
buffers would be sent to the server in the normal fashion. dirty buffers would be sent to the server in the normal fashion.
After a buffer is written by the client with the stable parameter set After a buffer is written by the client with the stable parameter set
to UNSTABLE4, the buffer must be considered as modified by the client to UNSTABLE4, the buffer must be considered as modified by the client
until the buffer has either been flushed via a COMMIT operation or until the buffer has either been flushed via a COMMIT operation or
written via a WRITE operation with stable parameter set to FILE_SYNC4 written via a WRITE operation with stable parameter set to FILE_SYNC4
or DATA_SYNC4. This is done to prevent the buffer from being freed or DATA_SYNC4. This is done to prevent the buffer from being freed
and reused before the data can be flushed to stable storage on the and reused before the data can be flushed to stable storage on the
server. server.
When a response is returned from either a WRITE or a COMMIT operation When a response is returned from either a WRITE or a COMMIT operation
and it contains a write verifier that is different than previously and it contains a write verifier that is different than previously
returned by the server, the client will need to retransmit all of the returned by the server, the client will need to retransmit all of the
buffers containing uncommitted cached data to the server. How this buffers containing uncommitted data to the server. How this is to be
is to be done is up to the implementor. If there is only one buffer done is up to the implementor. If there is only one buffer of
of interest, then it should probably be sent back over in a WRITE interest, then it should sent in a WRITE request with the FILE_SYNC4
request with the appropriate stable parameter. If there is more than stable parameter. If there is more than one buffer, it might be
one buffer, it might be worthwhile retransmitting all of the buffers worthwhile retransmitting all of the buffers in WRITE requests with
in WRITE requests with the stable parameter set to UNSTABLE4 and then the stable parameter set to UNSTABLE4 and then retransmitting the
retransmitting the COMMIT operation to flush all of the data on the COMMIT operation to flush all of the data on the server to stable
server to stable storage. The timing of these retransmissions is storage. However, if the server repeatably returns from COMMIT a
left to the implementor. verifier that differs from that returned by WRITE, the only way to
ensure progress is to retransmit all of the buffers with WRITE
requests with the FILE_SYNC4 stable parameter.
The above description applies to page-cache-based systems as well as The above description applies to page-cache-based systems as well as
buffer-cache-based systems. In those systems, the virtual memory buffer-cache-based systems. In those systems, the virtual memory
system will need to be modified instead of the buffer cache. system will need to be modified instead of the buffer cache.
18.4. Operation 6: CREATE - Create a Non-Regular File Object 18.4. Operation 6: CREATE - Create a Non-Regular File Object
18.4.1. ARGUMENTS 18.4.1. ARGUMENTS
union createtype4 switch (nfs_ftype4 type) { union createtype4 switch (nfs_ftype4 type) {
skipping to change at page 398, line 26 skipping to change at page 401, line 26
default: default:
void; void;
}; };
18.4.3. DESCRIPTION 18.4.3. DESCRIPTION
The CREATE operation creates a file object other than an ordinary The CREATE operation creates a file object other than an ordinary
file in a directory with a given name. The OPEN operation MUST be file in a directory with a given name. The OPEN operation MUST be
used to create a regular file or a named attribute. used to create a regular file or a named attribute.
The directory must be an object of type NF4DIR. If the current The current filehandle must be a directory: an object of type NF4DIR.
filehandle is an attribute directory (type NF4ATTRDIR), the error If the current filehandle is an attribute directory (type
NFS4ERR_WRONG_TYPE is returned. If the current file handle designate NF4ATTRDIR), the error NFS4ERR_WRONG_TYPE is returned. If the
any other type of object, the error NFS4ERR_NOTDIR results. current file handle designates any other type of object, the error
NFS4ERR_NOTDIR results.
The objname specifies the name for the new object. The objtype The objname specifies the name for the new object. The objtype
determines the type of object to be created: directory, symlink, etc. determines the type of object to be created: directory, symlink, etc.
If the object type specified is that of an ordinary file, a named If the object type specified is that of an ordinary file, a named
attribute, or a named attribute directory, the error NFS4ERR_BADTYPE attribute, or a named attribute directory, the error NFS4ERR_BADTYPE
results. results.
If an object of the same name already exists in the directory, the If an object of the same name already exists in the directory, the
server will return the error NFS4ERR_EXIST. server will return the error NFS4ERR_EXIST.
skipping to change at page 399, line 30 skipping to change at page 402, line 32
the RPC call's credentials, such as the group principal if the the RPC call's credentials, such as the group principal if the
credentials include it (such as with AUTH_SYS), from the group credentials include it (such as with AUTH_SYS), from the group
identifier associated with the principal in the credentials (for identifier associated with the principal in the credentials (for
e.g., POSIX systems have a passwd database that has the group e.g., POSIX systems have a passwd database that has the group
identifier for every user identifier), inherited from directory the identifier for every user identifier), inherited from directory the
object is created in, or whatever else the server's operating object is created in, or whatever else the server's operating
environment or file system semantics dictate. This applies to the environment or file system semantics dictate. This applies to the
OPEN operation too. OPEN operation too.
Conversely, it is possible the client will specify in createattrs an Conversely, it is possible the client will specify in createattrs an
owner attribute or group attribute or ACL that the principal owner attribute, group attribute, or ACL that the principal indicated
indicated the RPC call's credentials does not have permissions to the RPC call's credentials does not have permissions to create files
create files for. The error to be returned in this instance is for. The error to be returned in this instance is NFS4ERR_PERM.
NFS4ERR_PERM. This applies to the OPEN operation too. This applies to the OPEN operation too.
If the current filehandle designates a directory for which another If the current filehandle designates a directory for which another
client holds a directory delegation, then, unless the delegation is client holds a directory delegation, then, unless the delegation is
such that the situation can be resolved by sending a notification, such that the situation can be resolved by sending a notification,
the delegation must be recalled, and the operation cannot proceed the delegation MUST be recalled, and the CREATE operation MUST NOT
until the delegation is returned or revoked. Except where this proceed until the delegation is returned or revoked. Except where
happens very quickly, one or more NFS4ERR_DELAY errors will be this happens very quickly, one or more NFS4ERR_DELAY errors will be
returned to requests made while delegation remains outstanding. returned to requests made while delegation remains outstanding.
When the current filehandle designates a directory for which one or When the current filehandle designates a directory for which one or
more directory delegations exist, then, when those delegations more directory delegations exist, then, when those delegations
request such notifications, NOTIFY4_ADD_ENTRY will be generated as a request such notifications, NOTIFY4_ADD_ENTRY will be generated as a
result of this operation. result of this operation.
If the capability FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set If the capability FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set
(Section 14.4), and a symbolic link is being created, then the (Section 14.4), and a symbolic link is being created, then the
content of the symbolic link MUST be in UTF-8 encoding. content of the symbolic link MUST be in UTF-8 encoding.
skipping to change at page 401, line 30 skipping to change at page 404, line 30
18.6.3. DESCRIPTION 18.6.3. DESCRIPTION
Returns the delegation represented by the current filehandle and Returns the delegation represented by the current filehandle and
stateid. stateid.
Delegations may be returned when recalled or voluntarily (i.e. before Delegations may be returned when recalled or voluntarily (i.e. before
the server has recalled them). In either case the client must the server has recalled them). In either case the client must
properly propagate state changed under the context of the delegation properly propagate state changed under the context of the delegation
to the server before returning the delegation. to the server before returning the delegation.
The server MAY require that the principal, security flavor, and The server MAY require that the principal, security flavor, and if
applicable, the GSS mechanism, combination that acquired the applicable, the GSS mechanism, combination that acquired the
delegation also be the one to send DELEGRETURN on the file. This delegation also be the one to send DELEGRETURN on the file. This
might not be possible if credentials for the principal are no longer might not be possible if credentials for the principal are no longer
available. The server MAY allow the machine credential or SSV available. The server MAY allow the machine credential or SSV
credential (see Section 18.35) to send DELEGRETURN. credential (see Section 18.35) to send DELEGRETURN.
18.7. Operation 9: GETATTR - Get Attributes 18.7. Operation 9: GETATTR - Get Attributes
18.7.1. ARGUMENTS 18.7.1. ARGUMENTS
skipping to change at page 402, line 30 skipping to change at page 405, line 30
The GETATTR operation will obtain attributes for the file system The GETATTR operation will obtain attributes for the file system
object specified by the current filehandle. The client sets a bit in object specified by the current filehandle. The client sets a bit in
the bitmap argument for each attribute value that it would like the the bitmap argument for each attribute value that it would like the
server to return. The server returns an attribute bitmap that server to return. The server returns an attribute bitmap that
indicates the attribute values which it was able to return, which indicates the attribute values which it was able to return, which
will include all attributes requested by the client which are will include all attributes requested by the client which are
attributes supported by the server for the target file system. This attributes supported by the server for the target file system. This
bitmap is followed by the attribute values ordered lowest attribute bitmap is followed by the attribute values ordered lowest attribute
number first. number first.
The server must return a value for each attribute that the client The server MUST return a value for each attribute that the client
requests if the attribute is supported by the server for the target requests if the attribute is supported by the server for the target
file system. If the server does not support a particular attribute file system. If the server does not support a particular attribute
on the target file system then it must not return the attribute value on the target file system then it MUST NOT return the attribute value
and must not set the attribute bit in the result bitmap. The server and MUST NOT set the attribute bit in the result bitmap. The server
must return an error if it supports an attribute on the target but MUST return an error if it supports an attribute on the target but
cannot obtain its value. In that case, no attribute values will be cannot obtain its value. In that case, no attribute values will be
returned. returned.
File systems which are absent should be treated as having support for File systems which are absent should be treated as having support for
a very small set of attributes as described in GETATTR Within an a very small set of attributes as described in GETATTR Within an
Absent File System (Section 5), even if previously, when the file Absent File System (Section 5), even if previously, when the file
system was present, more attributes were supported. system was present, more attributes were supported.
All servers MUST support the REQUIRED attributes as specified in File All servers MUST support the REQUIRED attributes as specified in File
Attributes (Section 11.3.1), for all file systems, with the exception Attributes (Section 11.3.1), for all file systems, with the exception
of absent file systems. of absent file systems.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
18.7.4. IMPLEMENTATION 18.7.4. IMPLEMENTATION
When there is write delegation held by another client for file in Suppose there is a write delegation held by another client for file
question and the set of attributes being interrogated includes the in question and size and/or change are among the set of attributes
size of change attributes. the server needs to obtain the actual being interrogated. The server has two choices. First, the server
current value of these attributes from the client holding the can obtain the actual current value of these attributes from the
delegation by using the CB_GETATTR callback. The server, client holding the delegation by using the CB_GETATTR callback.
particularly, when the delegated client is unresponsive, choose Second, the server, particularly when the delegated client is
instead to recall the delegation in question. The GETATTR may not, unresponsive, can recall the delegation in question. The GETATTR
in this case proceed until of the following occurs: MUST NOT proceed until one of the following occurs:
o The requested attribute values are returned in the response to o The requested attribute values are returned in the response to
CB_GETATTR. CB_GETATTR.
o The write delegation is returned. o The write delegation is returned.
o The write delegation is revoked. o The write delegation is revoked.
Except where one of these happens very quickly, one or more Unless one of the above happens very quickly, one or more
NFS4ERR_DELAY errors will be returned to requests made while NFS4ERR_DELAY errors will be returned if while a delegation is
delegation remains outstanding. outstanding.
18.8. Operation 10: GETFH - Get Current Filehandle 18.8. Operation 10: GETFH - Get Current Filehandle
18.8.1. ARGUMENTS 18.8.1. ARGUMENTS
/* CURRENT_FH: */ /* CURRENT_FH: */
void; void;
18.8.2. RESULTS 18.8.2. RESULTS
skipping to change at page 404, line 5 skipping to change at page 407, line 5
default: default:
void; void;
}; };
18.8.3. DESCRIPTION 18.8.3. DESCRIPTION
This operation returns the current filehandle value. This operation returns the current filehandle value.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
As described in Section 2.10.5.4, GETFH is REQUIRED or RECOMMENDED to
immediately follow certain operations, and servers are free to reject
such operations the client fails to insert GETFH in the request as
REQUIRED or RECOMMENDED. Section 18.16.4.1 provides additional
justification for why GETFH MUST follow OPEN.
18.8.4. IMPLEMENTATION 18.8.4. IMPLEMENTATION
Operations that change the current filehandle like LOOKUP or CREATE Operations that change the current filehandle like LOOKUP or CREATE
do not automatically return the new filehandle as a result. For do not automatically return the new filehandle as a result. For
instance, if a client needs to lookup a directory entry and obtain instance, if a client needs to lookup a directory entry and obtain
its filehandle then the following request is needed. its filehandle then the following request is needed.
PUTFH (directory filehandle) PUTFH (directory filehandle)
LOOKUP (entry name) LOOKUP (entry name)
skipping to change at page 405, line 24 skipping to change at page 408, line 34
The server MAY impose restrictions on the LINK operation such that The server MAY impose restrictions on the LINK operation such that
LINK may not be done when the file is open or when that open is done LINK may not be done when the file is open or when that open is done
by particular protocols, or with particular options or access modes. by particular protocols, or with particular options or access modes.
When LINK is rejected because of such restrictions, the error When LINK is rejected because of such restrictions, the error
NFS4ERR_FILE_OPEN is returned. NFS4ERR_FILE_OPEN is returned.
If a server does implement such restrictions and those restrictions If a server does implement such restrictions and those restrictions
include cases of NFSv4 opens preventing successful execution of a include cases of NFSv4 opens preventing successful execution of a
link, the server needs to recall any delegations which could hide the link, the server needs to recall any delegations which could hide the
existence of opens relevant to that decision. This is because of the existence of opens relevant to that decision. The reason is that
fact that when a client holds a delegation, the server need not have when a client holds a delegation, the server might not have an
accurate picture of the opens for that client, since the client may accurate account of the opens for that client, since the client may
execute OPENs and CLOSEs locally. The LINK operation must be delayed execute OPENs and CLOSEs locally. The LINK operation must be delayed
only until a definitive result can be obtained. For example, if only until a definitive result can be obtained. E.g., suppose there
there are multiple delegations and one of them establishes an open are multiple delegations and one of them establishes an open whose
whose presence would prevent the link, given the server's semantics, presence would prevent the link. Given the server's semantics,
NFS4ERR_FILE_OPEN may be returned to the caller as soon as that NFS4ERR_FILE_OPEN may be returned to the caller as soon as that
delegation is returned without waiting for other delegations to be delegation is returned without waiting for other delegations to be
returned. Similarly, if such opens are not associated with returned. Similarly, if such opens are not associated with
delegations, NFS4ERR_FILE_OPEN can be returned immediately with no delegations, NFS4ERR_FILE_OPEN can be returned immediately with no
delegation recall being done. delegation recall being done.
If the current filehandle designates a directory for which another If the current filehandle designates a directory for which another
client holds a directory delegation, then, unless the delegation is client holds a directory delegation, then, unless the delegation is
such that the situation can be resolved by sending a notification, such that the situation can be resolved by sending a notification,
the delegation must be recalled, and the operation cannot be the delegation MUST be recalled, and the operation cannot be
performed successfully. until the delegation is returned or revoked. performed successfully. until the delegation is returned or revoked.
Except where this happens very quickly, one or more NFS4ERR_DELAY Except where this happens very quickly, one or more NFS4ERR_DELAY
errors will be returned to requests made while delegation remains errors will be returned to requests made while delegation remains
outstanding. outstanding.
When the current filehandle designates a directory for which one or When the current filehandle designates a directory for which one or
more directory delegations exist, then, when those delegations more directory delegations exist, then, when those delegations
request such notifications, NOTIFY4_ADD_ENTRY will be generated as a request such notifications, instead of a recall, NOTIFY4_ADD_ENTRY
result of this operation. will be generated as a result of the LINK operation.
If the current file system supports the numlinks attribute, and other If the current file system supports the numlinks attribute, and other
clients have delegations to the file being linked, then those clients have delegations to the file being linked, then those
delegations must be recalled and the operation may proceed until all delegations MUST be recalled and the LINK operation MUST NOT proceed
delegations are returned or revoked. Except where this happens very until all delegations are returned or revoked. Except where this
quickly, one or more NFS4ERR_DELAY errors will be returned to happens very quickly, one or more NFS4ERR_DELAY errors will be
requests made while delegation remains outstanding. returned to requests made while delegation remains outstanding.
Changes to any property of the "hard" linked files are reflected in Changes to any property of the "hard" linked files are reflected in
all of the linked files. When a link is made to a file, the all of the linked files. When a link is made to a file, the
attributes for the file should have a value for numlinks that is one attributes for the file should have a value for numlinks that is one
greater than the value before the LINK operation. greater than the value before the LINK operation.
The statement "file and the target directory must reside within the The statement "file and the target directory must reside within the
same file system on the server" means that the fsid fields in the same file system on the server" means that the fsid fields in the
attributes for the objects are the same. If they reside on different attributes for the objects are the same. If they reside on different
file systems, the error NFS4ERR_XDEV, is returned. This error may be file systems, the error NFS4ERR_XDEV is returned. This error may be
returned by some server when there is an internal partitioning of a returned by some server when there is an internal partitioning of a
file system which the LINK operation would violate. file system which the LINK operation would violate.
On some servers, the filenames, "." and "..", are illegal as newname On some servers, "." and ".." are illegal values for newname and the
and the error NFS4ERR_BADNAME will be returned if they are specified. error NFS4ERR_BADNAME will be returned if they are specified.
When the current filehandle designates a named attribute directory When the current filehandle designates a named attribute directory
and the object to be linked (the saved filehandle) is not a named and the object to be linked (the saved filehandle) is not a named
attribute for the same object, the error NFS4ERR_XDEV must be attribute for the same object, the error NFS4ERR_XDEV MUST be
returned. When the saved filehandle designates a named attribute and returned. When the saved filehandle designates a named attribute and
the current filehandle is not the appropriate named attribute the current filehandle is not the appropriate named attribute
directory, the error NFS4ERR_XDEV MUST also be returned. directory, the error NFS4ERR_XDEV MUST also be returned.
When the current filehandle designates a named attribute directory When the current filehandle designates a named attribute directory
and the object to be linked (the saved filehandle) is a named and the object to be linked (the saved filehandle) is a named
attribute within that directory, the server may return the error attribute within that directory, the server may return the error
NFS4ERR_NOTSUPP. NFS4ERR_NOTSUPP.
In the case that newname is already linked to the file represented by In the case that newname is already linked to the file represented by
skipping to change at page 440, line 25 skipping to change at page 443, line 25
18.20.3. DESCRIPTION 18.20.3. DESCRIPTION
Replaces the current filehandle with the filehandle that represents Replaces the current filehandle with the filehandle that represents
the public filehandle of the server's name space. This filehandle the public filehandle of the server's name space. This filehandle
may be different from the "root" filehandle which may be associated may be different from the "root" filehandle which may be associated
with some other directory on the server. with some other directory on the server.
PUTPUBFH also clears the current stateid. PUTPUBFH also clears the current stateid.
The public filehandle represents the concepts embodied in RFC2054 The public filehandle represents the concepts embodied in RFC2054
[32], RFC2055 [33], RFC2224 [41]. The intent for NFSv4.1 is that the [32], RFC2055 [33], RFC2224 [42]. The intent for NFSv4.1 is that the
public filehandle (represented by the PUTPUBFH operation) be used as public filehandle (represented by the PUTPUBFH operation) be used as
a method of providing WebNFS server compatibility with NFSv3. a method of providing WebNFS server compatibility with NFSv3.
The public filehandle and the root filehandle (represented by the The public filehandle and the root filehandle (represented by the
PUTROOTFH operation) SHOULD be equivalent. If the public and root PUTROOTFH operation) SHOULD be equivalent. If the public and root
filehandles are not equivalent, then the public filehandle MUST be a filehandles are not equivalent, then the public filehandle MUST be a
descendant of the root filehandle. descendant of the root filehandle.
See Section 16.2.3.1.1 for more details on the current filehandle. See Section 16.2.3.1.1 for more details on the current filehandle.
skipping to change at page 440, line 47 skipping to change at page 443, line 47
18.20.4. IMPLEMENTATION 18.20.4. IMPLEMENTATION
Used as the second operator (after SEQUENCE) in an NFS request to set Used as the second operator (after SEQUENCE) in an NFS request to set
the context for file accessing operations that follow in the same the context for file accessing operations that follow in the same
COMPOUND request. COMPOUND request.
With the NFSv3 public filehandle, the client is able to specify With the NFSv3 public filehandle, the client is able to specify
whether the path name provided in the LOOKUP should be evaluated as whether the path name provided in the LOOKUP should be evaluated as
either an absolute path relative to the server's root or relative to either an absolute path relative to the server's root or relative to
the public filehandle. RFC2224 [41] contains further discussion of the public filehandle. RFC2224 [42] contains further discussion of
the functionality. With NFSv4.1, that type of specification is not the functionality. With NFSv4.1, that type of specification is not
directly available in the LOOKUP operation. The reason for this is directly available in the LOOKUP operation. The reason for this is
because the component separators needed to specify absolute vs. because the component separators needed to specify absolute vs.
relative are not allowed in NFSv4. Therefore, the client is relative are not allowed in NFSv4. Therefore, the client is
responsible for constructing its request such that the use of either responsible for constructing its request such that the use of either
PUTROOTFH or PUTPUBFH are used to signify absolute or relative PUTROOTFH or PUTPUBFH are used to signify absolute or relative
evaluation of an NFS URL respectively. evaluation of an NFS URL respectively.
Note that there are warnings mentioned in RFC2224 [41] with respect Note that there are warnings mentioned in RFC2224 [42] with respect
to the use of absolute evaluation and the restrictions the server may to the use of absolute evaluation and the restrictions the server may
place on that evaluation with respect to how much of its namespace place on that evaluation with respect to how much of its namespace
has been made available. These same warnings apply to NFSv4.1. It has been made available. These same warnings apply to NFSv4.1. It
is likely, therefore that because of server implementation details, is likely, therefore that because of server implementation details,
an NFSv3 absolute public filehandle lookup may behave differently an NFSv3 absolute public filehandle lookup may behave differently
than an NFSv4.1 absolute resolution. than an NFSv4.1 absolute resolution.
There is a form of security negotiation as described in RFC2755 [42] There is a form of security negotiation as described in RFC2755 [43]
that uses the public filehandle and an overloading of the pathname. that uses the public filehandle and an overloading of the pathname.
This method is not available with NFSv4.1 as filehandles are not This method is not available with NFSv4.1 as filehandles are not
overloaded with special meaning and therefore do not provide the same overloaded with special meaning and therefore do not provide the same
framework as NFSv3. Clients should therefore use the security framework as NFSv3. Clients should therefore use the security
negotiation mechanisms described in Section 2.6. negotiation mechanisms described in Section 2.6.
18.21. Operation 24: PUTROOTFH - Set Root Filehandle 18.21. Operation 24: PUTROOTFH - Set Root Filehandle
18.21.1. ARGUMENTS 18.21.1. ARGUMENTS
skipping to change at page 574, line 43 skipping to change at page 577, line 43
Zeidner, "Internet Small Computer Systems Interface (iSCSI)", Zeidner, "Internet Small Computer Systems Interface (iSCSI)",
RFC 3720, April 2004. RFC 3720, April 2004.
[39] Snively, R., "Fibre Channel Protocol for SCSI, 2nd Version [39] Snively, R., "Fibre Channel Protocol for SCSI, 2nd Version
(FCP-2)", ANSI/INCITS 350-2003, Oct 2003. (FCP-2)", ANSI/INCITS 350-2003, Oct 2003.
[40] Weber, R., "Object-Based Storage Device Commands (OSD)", ANSI/ [40] Weber, R., "Object-Based Storage Device Commands (OSD)", ANSI/
INCITS 400-2004, July 2004, INCITS 400-2004, July 2004,
<http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf>. <http://www.t10.org/ftp/t10/drafts/osd/osd-r10.pdf>.
[41] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997. [41] The Open Group, "The Open Group Base Specifications Issue 6,
IEEE Std 1003.1, 2004 Edition", 2004.
[42] Chiu, A., Eisler, M., and B. Callaghan, "Security Negotiation [42] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997.
[43] Chiu, A., Eisler, M., and B. Callaghan, "Security Negotiation
for WebNFS", RFC 2755, January 2000. for WebNFS", RFC 2755, January 2000.
Appendix A. Acknowledgments Appendix A. Acknowledgments
The initial drafts for the SECINFO extensions were edited by Mike The initial drafts for the SECINFO extensions were edited by Mike
Eisler with contributions from Peng Dai, Sergey Klyushin, and Carl Eisler with contributions from Peng Dai, Sergey Klyushin, and Carl
Burnett. Burnett.
The initial drafts for the SESSIONS extensions were edited by Tom The initial drafts for the SESSIONS extensions were edited by Tom
Talpey, Spencer Shepler, Jon Bauman with contributions from Charles Talpey, Spencer Shepler, Jon Bauman with contributions from Charles
 End of changes. 64 change blocks. 
180 lines changed or deleted 335 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/