draft-ietf-nfsv4-rfc3010bis-00.txt   draft-ietf-nfsv4-rfc3010bis-01.txt 
NFS Version 4 Working Group S. Shepler NFS Version 4 Working Group S. Shepler
INTERNET-DRAFT Sun Microsystems, Inc. INTERNET-DRAFT Sun Microsystems, Inc.
Document: draft-ietf-nfsv4-rfc3010bis-00.txt C. Beame Document: draft-ietf-nfsv4-rfc3010bis-01.txt C. Beame
Hummingbird Ltd. Hummingbird Ltd.
B. Callaghan B. Callaghan
Sun Microsystems, Inc. Sun Microsystems, Inc.
M. Eisler M. Eisler
Zambeel, Inc. Zambeel, Inc.
D. Noveck D. Noveck
Network Appliance, Inc. Network Appliance, Inc.
D. Robinson D. Robinson
Sun Microsystems, Inc. Sun Microsystems, Inc.
R. Thurlow R. Thurlow
Sun Microsystems, Inc. Sun Microsystems, Inc.
November 2001 July 2002
NFS version 4 Protocol NFS version 4 Protocol
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 2, line 5 skipping to change at page 2, line 5
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.
Abstract Abstract
NFS version 4 is a distributed file system protocol which owes NFS version 4 is a distributed file system protocol which owes
heritage to NFS protocol versions 2 [RFC1094] and 3 [RFC1813]. heritage to NFS protocol versions 2 [RFC1094] and 3 [RFC1813].
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
Unlike earlier versions, the NFS version 4 protocol supports Unlike earlier versions, the NFS version 4 protocol supports
traditional file access while integrating support for file locking traditional file access while integrating support for file locking
and the mount protocol. In addition, support for strong security and the mount protocol. In addition, support for strong security
(and its negotiation), compound operations, client caching, and (and its negotiation), compound operations, client caching, and
internationalization have been added. Of course, attention has been internationalization have been added. Of course, attention has been
applied to making NFS version 4 operate well in an Internet applied to making NFS version 4 operate well in an Internet
environment. environment.
Copyright Copyright
Copyright (C) The Internet Society (2001). All Rights Reserved. Copyright (C) The Internet Society (2000-2002). All Rights Reserved.
Key Words Key Words
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119. document are to be interpreted as described in RFC 2119.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1. Overview of NFS Version 4 Features . . . . . . . . . . . . 7 1.1. Overview of NFS Version 4 Features . . . . . . . . . . . . 7
1.1.1. RPC and Security . . . . . . . . . . . . . . . . . . . . 8 1.1.1. RPC and Security . . . . . . . . . . . . . . . . . . . . 8
1.1.2. Procedure and Operation Structure . . . . . . . . . . . 8 1.1.2. Procedure and Operation Structure . . . . . . . . . . . 8
1.1.3. File System Model . . . . . . . . . . . . . . . . . . . 9 1.1.3. File System Model . . . . . . . . . . . . . . . . . . . 9
1.1.3.1. Filehandle Types . . . . . . . . . . . . . . . . . . . 9 1.1.3.1. Filehandle Types . . . . . . . . . . . . . . . . . . . 9
1.1.3.2. Attribute Types . . . . . . . . . . . . . . . . . . . 9 1.1.3.2. Attribute Types . . . . . . . . . . . . . . . . . . . 9
skipping to change at page 3, line 52 skipping to change at page 3, line 52
4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 28 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . . 28
4.2.4. One Method of Constructing a Volatile Filehandle . . . 30 4.2.4. One Method of Constructing a Volatile Filehandle . . . 30
4.3. Client Recovery from Filehandle Expiration . . . . . . . 30 4.3. Client Recovery from Filehandle Expiration . . . . . . . 30
5. File Attributes . . . . . . . . . . . . . . . . . . . . . 32 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 32
5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 33 5.1. Mandatory Attributes . . . . . . . . . . . . . . . . . . 33
5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 33 5.2. Recommended Attributes . . . . . . . . . . . . . . . . . 33
5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 33 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 33
5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 35 5.4. Mandatory Attributes - Definitions . . . . . . . . . . . 35
5.5. Recommended Attributes - Definitions . . . . . . . . . . 37 5.5. Recommended Attributes - Definitions . . . . . . . . . . 37
5.6. Interpreting owner and owner_group . . . . . . . . . . . 41 5.6. Interpreting owner and owner_group . . . . . . . . . . . 41
5.7. Character Case Attributes . . . . . . . . . . . . . . . 42 5.7. Character Case Attributes . . . . . . . . . . . . . . . 43
5.8. Quota Attributes . . . . . . . . . . . . . . . . . . . . 42 5.8. Quota Attributes . . . . . . . . . . . . . . . . . . . . 43
5.9. Access Control Lists . . . . . . . . . . . . . . . . . . 43 5.9. Access Control Lists . . . . . . . . . . . . . . . . . . 44
5.9.1. ACE type . . . . . . . . . . . . . . . . . . . . . . . 44 5.9.1. ACE type . . . . . . . . . . . . . . . . . . . . . . . 45
5.9.2. ACE flag . . . . . . . . . . . . . . . . . . . . . . . 44 5.9.2. ACE flag . . . . . . . . . . . . . . . . . . . . . . . 45
5.9.3. ACE Access Mask . . . . . . . . . . . . . . . . . . . 46 5.9.3. ACE Access Mask . . . . . . . . . . . . . . . . . . . 47
5.9.4. ACE who . . . . . . . . . . . . . . . . . . . . . . . 47 5.9.4. ACE who . . . . . . . . . . . . . . . . . . . . . . . 48
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
6. File System Migration and Replication . . . . . . . . . . 48 6. File System Migration and Replication . . . . . . . . . . 49
6.1. Replication . . . . . . . . . . . . . . . . . . . . . . 48 6.1. Replication . . . . . . . . . . . . . . . . . . . . . . 49
6.2. Migration . . . . . . . . . . . . . . . . . . . . . . . 48 6.2. Migration . . . . . . . . . . . . . . . . . . . . . . . 49
6.3. Interpretation of the fs_locations Attribute . . . . . . 49 6.3. Interpretation of the fs_locations Attribute . . . . . . 50
6.4. Filehandle Recovery for Migration or Replication . . . . 50 6.4. Filehandle Recovery for Migration or Replication . . . . 51
7. NFS Server Name Space . . . . . . . . . . . . . . . . . . 51 7. NFS Server Name Space . . . . . . . . . . . . . . . . . . 52
7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 51 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 52
7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 51 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 52
7.3. Server Pseudo File System . . . . . . . . . . . . . . . 51 7.3. Server Pseudo File System . . . . . . . . . . . . . . . 52
7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 52 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 53
7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 52 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 53
7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 52 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 53
7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 53 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 54
7.8. Security Policy and Name Space Presentation . . . . . . 53 7.8. Security Policy and Name Space Presentation . . . . . . 54
8. File Locking and Share Reservations . . . . . . . . . . . 54 8. File Locking and Share Reservations . . . . . . . . . . . 55
8.1. Locking . . . . . . . . . . . . . . . . . . . . . . . . 54 8.1. Locking . . . . . . . . . . . . . . . . . . . . . . . . 55
8.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 54 8.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . . 55
8.1.2. Server Release of Clientid . . . . . . . . . . . . . . 56 8.1.2. Server Release of Clientid . . . . . . . . . . . . . . 57
8.1.3. nfs_lockowner and stateid Definition . . . . . . . . . 57 8.1.3. nfs_lockowner and stateid Definition . . . . . . . . . 58
8.1.4. Use of the stateid . . . . . . . . . . . . . . . . . . 58 8.1.4. Use of the stateid . . . . . . . . . . . . . . . . . . 59
8.1.5. Sequencing of Lock Requests . . . . . . . . . . . . . 58 8.1.5. Sequencing of Lock Requests . . . . . . . . . . . . . 60
8.1.6. Recovery from Replayed Requests . . . . . . . . . . . 59 8.1.6. Recovery from Replayed Requests . . . . . . . . . . . 61
8.1.7. Releasing nfs_lockowner State . . . . . . . . . . . . 59 8.1.7. Releasing nfs_lockowner State . . . . . . . . . . . . 61
8.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 60 8.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 62
8.3. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 61 8.3. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 62
8.4. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 61 8.4. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 63
8.5. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 62 8.5. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 64
8.5.1. Client Failure and Recovery . . . . . . . . . . . . . 62 8.5.1. Client Failure and Recovery . . . . . . . . . . . . . 64
8.5.2. Server Failure and Recovery . . . . . . . . . . . . . 63 8.5.2. Server Failure and Recovery . . . . . . . . . . . . . 65
8.5.3. Network Partitions and Recovery . . . . . . . . . . . 64 8.5.3. Network Partitions and Recovery . . . . . . . . . . . 66
8.6. Recovery from a Lock Request Timeout or Abort . . . . . 65 8.6. Recovery from a Lock Request Timeout or Abort . . . . . 67
8.7. Server Revocation of Locks . . . . . . . . . . . . . . . 66 8.7. Server Revocation of Locks . . . . . . . . . . . . . . . 68
8.8. Share Reservations . . . . . . . . . . . . . . . . . . . 67 8.8. Share Reservations . . . . . . . . . . . . . . . . . . . 69
8.9. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 68 8.9. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 69
8.10. Open Upgrade and Downgrade . . . . . . . . . . . . . . 68 8.10. Open Upgrade and Downgrade . . . . . . . . . . . . . . 70
8.11. Short and Long Leases . . . . . . . . . . . . . . . . . 69 8.11. Short and Long Leases . . . . . . . . . . . . . . . . . 71
8.12. Clocks and Calculating Lease Expiration . . . . . . . . 69 8.12. Clocks and Calculating Lease Expiration . . . . . . . . 71
8.13. Migration, Replication and State . . . . . . . . . . . 70 8.13. Migration, Replication and State . . . . . . . . . . . 71
8.13.1. Migration and State . . . . . . . . . . . . . . . . . 70 8.13.1. Migration and State . . . . . . . . . . . . . . . . . 72
8.13.2. Replication and State . . . . . . . . . . . . . . . . 70 8.13.2. Replication and State . . . . . . . . . . . . . . . . 72
8.13.3. Notification of Migrated Lease . . . . . . . . . . . 71 8.13.3. Notification of Migrated Lease . . . . . . . . . . . 73
9. Client-Side Caching . . . . . . . . . . . . . . . . . . . 72 9. Client-Side Caching . . . . . . . . . . . . . . . . . . . 74
9.1. Performance Challenges for Client-Side Caching . . . . . 72 9.1. Performance Challenges for Client-Side Caching . . . . . 74
9.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 73 9.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 75
9.2.1. Delegation Recovery . . . . . . . . . . . . . . . . . 74 9.2.1. Delegation Recovery . . . . . . . . . . . . . . . . . 76
9.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 76 9.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 78
9.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . . 76 9.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . . 78
9.3.2. Data Caching and File Locking . . . . . . . . . . . . 77 9.3.2. Data Caching and File Locking . . . . . . . . . . . . 79
9.3.3. Data Caching and Mandatory File Locking . . . . . . . 78 9.3.3. Data Caching and Mandatory File Locking . . . . . . . 80
9.3.4. Data Caching and File Identity . . . . . . . . . . . . 79 9.3.4. Data Caching and File Identity . . . . . . . . . . . . 81
9.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 80 9.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 82
9.4.1. Open Delegation and Data Caching . . . . . . . . . . . 82 9.4.1. Open Delegation and Data Caching . . . . . . . . . . . 84
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
9.4.2. Open Delegation and File Locks . . . . . . . . . . . . 83 9.4.2. Open Delegation and File Locks . . . . . . . . . . . . 85
9.4.3. Recall of Open Delegation . . . . . . . . . . . . . . 83 9.4.3. Recall of Open Delegation . . . . . . . . . . . . . . 85
9.4.4. Delegation Revocation . . . . . . . . . . . . . . . . 85 9.4.4. Delegation Revocation . . . . . . . . . . . . . . . . 87
9.5. Data Caching and Revocation . . . . . . . . . . . . . . 85 9.5. Data Caching and Revocation . . . . . . . . . . . . . . 87
9.5.1. Revocation Recovery for Write Open Delegation . . . . 86 9.5.1. Revocation Recovery for Write Open Delegation . . . . 88
9.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 87 9.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 89
9.7. Name Caching . . . . . . . . . . . . . . . . . . . . . . 88 9.7. Name Caching . . . . . . . . . . . . . . . . . . . . . . 90
9.8. Directory Caching . . . . . . . . . . . . . . . . . . . 89 9.8. Directory Caching . . . . . . . . . . . . . . . . . . . 91
10. Minor Versioning . . . . . . . . . . . . . . . . . . . . 91 10. Minor Versioning . . . . . . . . . . . . . . . . . . . . 93
11. Internationalization . . . . . . . . . . . . . . . . . . 94 11. Internationalization . . . . . . . . . . . . . . . . . . 96
11.1. Universal Versus Local Character Sets . . . . . . . . . 94 11.1. Universal Versus Local Character Sets . . . . . . . . . 96
11.2. Overview of Universal Character Set Standards . . . . . 95 11.2. Overview of Universal Character Set Standards . . . . . 97
11.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 96 11.3. Difficulties with UCS-4, UCS-2, Unicode . . . . . . . . 98
11.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 96 11.4. UTF-8 and its solutions . . . . . . . . . . . . . . . . 98
11.5. Normalization . . . . . . . . . . . . . . . . . . . . . 97 11.5. Normalization . . . . . . . . . . . . . . . . . . . . . 99
12. Error Definitions . . . . . . . . . . . . . . . . . . . . 98 12. Error Definitions . . . . . . . . . . . . . . . . . . . . 100
13. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 103 13. NFS Version 4 Requests . . . . . . . . . . . . . . . . . 105
13.1. Compound Procedure . . . . . . . . . . . . . . . . . . 103 13.1. Compound Procedure . . . . . . . . . . . . . . . . . . 105
13.2. Evaluation of a Compound Request . . . . . . . . . . . 103 13.2. Evaluation of a Compound Request . . . . . . . . . . . 106
13.3. Synchronous Modifying Operations . . . . . . . . . . . 104 13.3. Synchronous Modifying Operations . . . . . . . . . . . 106
13.4. Operation Values . . . . . . . . . . . . . . . . . . . 105 13.4. Operation Values . . . . . . . . . . . . . . . . . . . 107
14. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 106 14. NFS Version 4 Procedures . . . . . . . . . . . . . . . . 108
14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 106 14.1. Procedure 0: NULL - No Operation . . . . . . . . . . . 108
14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 107 14.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 109
14.2.1. Operation 3: ACCESS - Check Access Rights . . . . . . 110 14.2.1. Operation 3: ACCESS - Check Access Rights . . . . . . 112
14.2.2. Operation 4: CLOSE - Close File . . . . . . . . . . . 113 14.2.2. Operation 4: CLOSE - Close File . . . . . . . . . . . 115
14.2.3. Operation 5: COMMIT - Commit Cached Data . . . . . . 115 14.2.3. Operation 5: COMMIT - Commit Cached Data . . . . . . 117
14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 118 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 120
14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting
Recovery . . . . . . . . . . . . . . . . . . . . . . 120 Recovery . . . . . . . . . . . . . . . . . . . . . . 123
14.2.6. Operation 8: DELEGRETURN - Return Delegation . . . . 121 14.2.6. Operation 8: DELEGRETURN - Return Delegation . . . . 124
14.2.7. Operation 9: GETATTR - Get Attributes . . . . . . . . 122 14.2.7. Operation 9: GETATTR - Get Attributes . . . . . . . . 125
14.2.8. Operation 10: GETFH - Get Current Filehandle . . . . 124 14.2.8. Operation 10: GETFH - Get Current Filehandle . . . . 127
14.2.9. Operation 11: LINK - Create Link to a File . . . . . 126 14.2.9. Operation 11: LINK - Create Link to a File . . . . . 129
14.2.10. Operation 12: LOCK - Create Lock . . . . . . . . . . 128 14.2.10. Operation 12: LOCK - Create Lock . . . . . . . . . . 131
14.2.11. Operation 13: LOCKT - Test For Lock . . . . . . . . 130 14.2.11. Operation 13: LOCKT - Test For Lock . . . . . . . . 134
14.2.12. Operation 14: LOCKU - Unlock File . . . . . . . . . 132 14.2.12. Operation 14: LOCKU - Unlock File . . . . . . . . . 136
14.2.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . 134 14.2.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . 138
14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory . . 137 14.2.14. Operation 16: LOOKUPP - Lookup Parent Directory . . 141
14.2.15. Operation 17: NVERIFY - Verify Difference in 14.2.15. Operation 17: NVERIFY - Verify Difference in
Attributes . . . . . . . . . . . . . . . . . . . . . 139 Attributes . . . . . . . . . . . . . . . . . . . . . 143
14.2.16. Operation 18: OPEN - Open a Regular File . . . . . . 141 14.2.16. Operation 18: OPEN - Open a Regular File . . . . . . 145
14.2.17. Operation 19: OPENATTR - Open Named Attribute 14.2.17. Operation 19: OPENATTR - Open Named Attribute
Directory . . . . . . . . . . . . . . . . . . . . . 150 Directory . . . . . . . . . . . . . . . . . . . . . 154
14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . 152 14.2.18. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . 156
14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access155 14.2.19. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access159
14.2.20. Operation 22: PUTFH - Set Current Filehandle . . . . 157 14.2.20. Operation 22: PUTFH - Set Current Filehandle . . . . 161
14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle . . . 158 14.2.21. Operation 23: PUTPUBFH - Set Public Filehandle . . . 162
14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle . . . 159 14.2.22. Operation 24: PUTROOTFH - Set Root Filehandle . . . 164
14.2.23. Operation 25: READ - Read from File . . . . . . . . 160 14.2.23. Operation 25: READ - Read from File . . . . . . . . 165
14.2.24. Operation 26: READDIR - Read Directory . . . . . . . 163 14.2.24. Operation 26: READDIR - Read Directory . . . . . . . 168
14.2.25. Operation 27: READLINK - Read Symbolic Link . . . . 167 14.2.25. Operation 27: READLINK - Read Symbolic Link . . . . 172
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.26. Operation 28: REMOVE - Remove Filesystem Object . . 169 14.2.26. Operation 28: REMOVE - Remove Filesystem Object . . 174
14.2.27. Operation 29: RENAME - Rename Directory Entry . . . 171 14.2.27. Operation 29: RENAME - Rename Directory Entry . . . 176
14.2.28. Operation 30: RENEW - Renew a Lease . . . . . . . . 174 14.2.28. Operation 30: RENEW - Renew a Lease . . . . . . . . 179
14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle . 175 14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle . 180
14.2.30. Operation 32: SAVEFH - Save Current Filehandle . . . 177 14.2.30. Operation 32: SAVEFH - Save Current Filehandle . . . 182
14.2.31. Operation 33: SECINFO - Obtain Available Security . 178 14.2.31. Operation 33: SECINFO - Obtain Available Security . 183
14.2.32. Operation 34: SETATTR - Set Attributes . . . . . . . 180 14.2.32. Operation 34: SETATTR - Set Attributes . . . . . . . 186
14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid . . . 182 14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid . . . 189
14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 184 14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid 191
14.2.35. Operation 37: VERIFY - Verify Same Attributes . . . 185 14.2.35. Operation 37: VERIFY - Verify Same Attributes . . . 192
14.2.36. Operation 38: WRITE - Write to File . . . . . . . . 187 14.2.36. Operation 38: WRITE - Write to File . . . . . . . . 194
15. NFS Version 4 Callback Procedures . . . . . . . . . . . . 191 14.2.37. Operation 39: RELEASE_LOCKOWNER - Release Lockowner
15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 191 State . . . . . . . . . . . . . . . . . . . . . . . 198
15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 192 15. NFS Version 4 Callback Procedures . . . . . . . . . . . . 199
15.2.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . 194 15.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 199
15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation . 195 15.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . 200
16. Security Considerations . . . . . . . . . . . . . . . . . 197 15.2.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . 202
17. IANA Considerations . . . . . . . . . . . . . . . . . . . 198 15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation . 203
17.1. Named Attribute Definition . . . . . . . . . . . . . . 198 16. Security Considerations . . . . . . . . . . . . . . . . . 205
18. RPC definition file . . . . . . . . . . . . . . . . . . . 199 17. IANA Considerations . . . . . . . . . . . . . . . . . . . 206
19. Bibliography . . . . . . . . . . . . . . . . . . . . . . 229 17.1. Named Attribute Definition . . . . . . . . . . . . . . 206
20. Authors . . . . . . . . . . . . . . . . . . . . . . . . . 234 18. RPC definition file . . . . . . . . . . . . . . . . . . . 207
20.1. Editor's Address . . . . . . . . . . . . . . . . . . . 234 19. Bibliography . . . . . . . . . . . . . . . . . . . . . . 238
20.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 234 20. Authors . . . . . . . . . . . . . . . . . . . . . . . . . 243
20.3. Acknowledgements . . . . . . . . . . . . . . . . . . . 235 20.1. Editor's Address . . . . . . . . . . . . . . . . . . . 243
21. Full Copyright Statement . . . . . . . . . . . . . . . . 236 20.2. Authors' Addresses . . . . . . . . . . . . . . . . . . 243
20.3. Acknowledgements . . . . . . . . . . . . . . . . . . . 244
21. Full Copyright Statement . . . . . . . . . . . . . . . . 245
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
1. Introduction 1. Introduction
The NFS version 4 protocol is a further revision of the NFS protocol The NFS version 4 protocol is a further revision of the NFS protocol
defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains defined already by versions 2 [RFC1094] and 3 [RFC1813]. It retains
the essential characteristics of previous versions: design for easy the essential characteristics of previous versions: design for easy
recovery, independent of transport protocols, operating systems and recovery, independent of transport protocols, operating systems and
filesystems, simplicity, and good performance. The NFS version 4 filesystems, simplicity, and good performance. The NFS version 4
revision has the following goals: revision has the following goals:
skipping to change at page 8, line 5 skipping to change at page 8, line 5
To provide a reasonable context for the reader, the major features of To provide a reasonable context for the reader, the major features of
NFS version 4 protocol will be reviewed in brief. This will be done NFS version 4 protocol will be reviewed in brief. This will be done
to provide an appropriate context for both the reader who is familiar to provide an appropriate context for both the reader who is familiar
with the previous versions of the NFS protocol and the reader that is with the previous versions of the NFS protocol and the reader that is
new to the NFS protocols. For the reader new to the NFS protocols, new to the NFS protocols. For the reader new to the NFS protocols,
there is still a fundamental knowledge that is expected. The reader there is still a fundamental knowledge that is expected. The reader
should be familiar with the XDR and RPC protocols as described in should be familiar with the XDR and RPC protocols as described in
[RFC1831] and [RFC1832]. A basic knowledge of file systems and [RFC1831] and [RFC1832]. A basic knowledge of file systems and
distributed file systems is expected as well. distributed file systems is expected as well.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
1.1.1. RPC and Security 1.1.1. RPC and Security
As with previous versions of NFS, the External Data Representation As with previous versions of NFS, the External Data Representation
(XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFS
version 4 protocol are those defined in [RFC1831] and [RFC1832]. To version 4 protocol are those defined in [RFC1831] and [RFC1832]. To
meet end to end security requirements, the RPCSEC_GSS framework meet end to end security requirements, the RPCSEC_GSS framework
[RFC2203] will be used to extend the basic RPC security. With the [RFC2203] will be used to extend the basic RPC security. With the
use of RPCSEC_GSS, various mechanisms can be provided to offer use of RPCSEC_GSS, various mechanisms can be provided to offer
authentication, integrity, and privacy to the NFS version 4 protocol. authentication, integrity, and privacy to the NFS version 4 protocol.
skipping to change at page 9, line 5 skipping to change at page 9, line 5
request are evaluated in order by the server. Once an operation request are evaluated in order by the server. Once an operation
returns a failing result, the evaluation ends and the results of all returns a failing result, the evaluation ends and the results of all
evaluated operations are returned to the client. evaluated operations are returned to the client.
The NFS version 4 protocol continues to have the client refer to a The NFS version 4 protocol continues to have the client refer to a
file or directory at the server by a "filehandle". The COMPOUND file or directory at the server by a "filehandle". The COMPOUND
procedure has a method of passing a filehandle from one operation to procedure has a method of passing a filehandle from one operation to
another within the sequence of operations. There is a concept of a another within the sequence of operations. There is a concept of a
"current filehandle" and "saved filehandle". Most operations use the "current filehandle" and "saved filehandle". Most operations use the
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
"current filehandle" as the file system object to operate upon. The "current filehandle" as the file system object to operate upon. The
"saved filehandle" is used as temporary filehandle storage within a "saved filehandle" is used as temporary filehandle storage within a
COMPOUND procedure as well as an additional operand for certain COMPOUND procedure as well as an additional operand for certain
operations. operations.
1.1.3. File System Model 1.1.3. File System Model
The general file system model used for the NFS version 4 protocol is The general file system model used for the NFS version 4 protocol is
the same as previous versions. The server file system is the same as previous versions. The server file system is
skipping to change at page 10, line 5 skipping to change at page 10, line 5
file attributes. Like the additional filehandle type, the file attributes. Like the additional filehandle type, the
classification of file attributes has been done to ease server classification of file attributes has been done to ease server
implementations along with extending the overall functionality of the implementations along with extending the overall functionality of the
NFS protocol. This attribute model is structured to be extensible NFS protocol. This attribute model is structured to be extensible
such that new attributes can be introduced in minor revisions of the such that new attributes can be introduced in minor revisions of the
protocol without requiring significant rework. protocol without requiring significant rework.
The three classifications are: mandatory, recommended and named The three classifications are: mandatory, recommended and named
attributes. This is a significant departure from the previous attributes. This is a significant departure from the previous
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
attribute model used in the NFS protocol. Previously, the attributes attribute model used in the NFS protocol. Previously, the attributes
for the file system and file objects were a fixed set of mainly Unix for the file system and file objects were a fixed set of mainly Unix
attributes. If the server or client did not support a particular attributes. If the server or client did not support a particular
attribute, it would have to simulate the attribute the best it could. attribute, it would have to simulate the attribute the best it could.
Mandatory attributes are the minimal set of file or file system Mandatory attributes are the minimal set of file or file system
attributes that must be provided by the server and must be properly attributes that must be provided by the server and must be properly
represented by the server. Recommended attributes represent represented by the server. Recommended attributes represent
different file system types and operating environments. The different file system types and operating environments. The
skipping to change at page 11, line 5 skipping to change at page 11, line 5
The NFS version 4 protocol introduces OPEN and CLOSE operations. The The NFS version 4 protocol introduces OPEN and CLOSE operations. The
OPEN operation provides a single point where file lookup, creation, OPEN operation provides a single point where file lookup, creation,
and share semantics can be combined. The CLOSE operation also and share semantics can be combined. The CLOSE operation also
provides for the release of state accumulated by OPEN. provides for the release of state accumulated by OPEN.
1.1.5. File locking 1.1.5. File locking
With the NFS version 4 protocol, the support for byte range file With the NFS version 4 protocol, the support for byte range file
locking is part of the NFS protocol. The file locking support is locking is part of the NFS protocol. The file locking support is
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
structured so that an RPC callback mechanism is not required. This structured so that an RPC callback mechanism is not required. This
is a departure from the previous versions of the NFS file locking is a departure from the previous versions of the NFS file locking
protocol, Network Lock Manager (NLM). The state associated with file protocol, Network Lock Manager (NLM). The state associated with file
locks is maintained at the server under a lease-based model. The locks is maintained at the server under a lease-based model. The
server defines a single lease period for all state held by a NFS server defines a single lease period for all state held by a NFS
client. If the client does not renew its lease within the defined client. If the client does not renew its lease within the defined
period, all state associated with the client's lease may be released period, all state associated with the client's lease may be released
by the server. The client may renew its lease with use of the RENEW by the server. The client may renew its lease with use of the RENEW
operation or implicitly by use of other operations (primarily READ). operation or implicitly by use of other operations (primarily READ).
skipping to change at page 12, line 5 skipping to change at page 12, line 5
Delegations can be recalled by the server. If another client Delegations can be recalled by the server. If another client
requests access to the file in such a way that the access conflicts requests access to the file in such a way that the access conflicts
with the granted delegation, the server is able to notify the initial with the granted delegation, the server is able to notify the initial
client and recall the delegation. This requires that a callback path client and recall the delegation. This requires that a callback path
exist between the server and client. If this callback path does not exist between the server and client. If this callback path does not
exist, then delegations can not be granted. The essence of a exist, then delegations can not be granted. The essence of a
delegation is that it allows the client to locally service operations delegation is that it allows the client to locally service operations
such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate
interaction with the server. interaction with the server.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
1.2. General Definitions 1.2. General Definitions
The following definitions are provided for the purpose of providing The following definitions are provided for the purpose of providing
an appropriate context for the reader. an appropriate context for the reader.
Client The "client" is the entity that accesses the NFS server's Client The "client" is the entity that accesses the NFS server's
resources. The client may be an application which contains resources. The client may be an application which contains
the logic to access the NFS server directly. The client the logic to access the NFS server directly. The client
may also be the traditional operating system client remote may also be the traditional operating system client remote
skipping to change at page 13, line 5 skipping to change at page 13, line 5
NFS version 4 servers must be able to recover without data NFS version 4 servers must be able to recover without data
loss from multiple power failures (including cascading loss from multiple power failures (including cascading
power failures, that is, several power failures in quick power failures, that is, several power failures in quick
succession), operating system failures, and hardware succession), operating system failures, and hardware
failure of components other than the storage medium itself failure of components other than the storage medium itself
(for example, disk, nonvolatile RAM). (for example, disk, nonvolatile RAM).
Some examples of stable storage that are allowable for an Some examples of stable storage that are allowable for an
NFS server include: NFS server include:
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
1. Media commit of data, that is, the modified data has 1. Media commit of data, that is, the modified data has
been successfully written to the disk media, been successfully written to the disk media,
for example, the disk platter. for example, the disk platter.
2. An immediate reply disk drive with battery-backed 2. An immediate reply disk drive with battery-backed
on-drive intermediate storage or uninterruptible power on-drive intermediate storage or uninterruptible power
system (UPS). system (UPS).
3. Server commit of data with battery-backed intermediate 3. Server commit of data with battery-backed intermediate
storage and recovery software. storage and recovery software.
4. Cache commit with uninterruptible power system (UPS) 4. Cache commit with uninterruptible power system (UPS)
and recovery software. and recovery software.
Stateid A 64-bit quantity returned by a server that uniquely Stateid A 128-bit quantity returned by a server that uniquely
defines the locking state granted by the server for a defines the open and locking state provided by the server
specific lock owner for a specific file. for a specific open or lock owner for a specific file.
Stateids composed of all bits 0 or all bits 1 have special Stateids composed of all bits 0 or all bits 1 have special
meaning and are reserved values. meaning and are reserved values.
Verifier A 64-bit quantity generated by the client that the server Verifier A 64-bit quantity generated by the client that the server
can use to determine if the client has restarted and lost can use to determine if the client has restarted and lost
all previous lock state. all previous lock state.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
2. Protocol Data Types 2. Protocol Data Types
The syntax and semantics to describe the data types of the NFS The syntax and semantics to describe the data types of the NFS
version 4 protocol are defined in the XDR [RFC1832] and RPC [RFC1831] version 4 protocol are defined in the XDR [RFC1832] and RPC [RFC1831]
documents. The next sections build upon the XDR data types to define documents. The next sections build upon the XDR data types to define
types and structures specific to this protocol. types and structures specific to this protocol.
2.1. Basic Data Types 2.1. Basic Data Types
skipping to change at page 15, line 5 skipping to change at page 15, line 5
mode4 typedef uint32_t mode4; mode4 typedef uint32_t mode4;
Mode attribute data type Mode attribute data type
nfs_cookie4 typedef uint64_t nfs_cookie4; nfs_cookie4 typedef uint64_t nfs_cookie4;
Opaque cookie value for READDIR Opaque cookie value for READDIR
nfs_fh4 typedef opaque nfs_fh4<NFS4_FHSIZE>; nfs_fh4 typedef opaque nfs_fh4<NFS4_FHSIZE>;
Filehandle definition; NFS4_FHSIZE is defined as 128 Filehandle definition; NFS4_FHSIZE is defined as 128
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
nfs_ftype4 enum nfs_ftype4; nfs_ftype4 enum nfs_ftype4;
Various defined file types Various defined file types
nfsstat4 enum nfsstat4; nfsstat4 enum nfsstat4;
Return value for operations Return value for operations
offset4 typedef uint64_t offset4; offset4 typedef uint64_t offset4;
Various offset designations (READ, WRITE, LOCK, COMMIT) Various offset designations (READ, WRITE, LOCK, COMMIT)
skipping to change at page 16, line 5 skipping to change at page 16, line 5
The nfstime4 structure gives the number of seconds and The nfstime4 structure gives the number of seconds and
nanoseconds since midnight or 0 hour January 1, 1970 Coordinated nanoseconds since midnight or 0 hour January 1, 1970 Coordinated
Universal Time (UTC). Values greater than zero for the seconds Universal Time (UTC). Values greater than zero for the seconds
field denote dates after the 0 hour January 1, 1970. Values field denote dates after the 0 hour January 1, 1970. Values
less than zero for the seconds field denote dates before the 0 less than zero for the seconds field denote dates before the 0
hour January 1, 1970. In both cases, the nseconds field is to hour January 1, 1970. In both cases, the nseconds field is to
be added to the seconds field for the final time representation. be added to the seconds field for the final time representation.
For example, if the time to be represented is one-half second For example, if the time to be represented is one-half second
before 0 hour January 1, 1970, the seconds field would have a before 0 hour January 1, 1970, the seconds field would have a
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
value of negative one (-1) and the nseconds fields would have a value of negative one (-1) and the nseconds fields would have a
value of one-half second (500000000). Values greater than value of one-half second (500000000). Values greater than
999,999,999 for nseconds are considered invalid. 999,999,999 for nseconds are considered invalid.
This data type is used to pass time and date information. A This data type is used to pass time and date information. A
server converts to and from its local representation of time server converts to and from its local representation of time
when processing time values, preserving as much accuracy as when processing time values, preserving as much accuracy as
possible. If the precision of timestamps stored for a file possible. If the precision of timestamps stored for a file
system object is less than defined, loss of precision can occur. system object is less than defined, loss of precision can occur.
skipping to change at page 17, line 5 skipping to change at page 17, line 5
This data type represents additional information for the device This data type represents additional information for the device
file types NF4CHR and NF4BLK. file types NF4CHR and NF4BLK.
fsid4 fsid4
struct fsid4 { struct fsid4 {
uint64_t major; uint64_t major;
uint64_t minor; uint64_t minor;
}; };
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
This type is the file system identifier that is used as a This type is the file system identifier that is used as a
mandatory attribute. mandatory attribute.
fs_location4 fs_location4
struct fs_location4 { struct fs_location4 {
utf8string server<>; utf8string server<>;
pathname4 rootpath; pathname4 rootpath;
}; };
skipping to change at page 18, line 5 skipping to change at page 18, line 5
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
change_info4 change_info4
struct change_info4 { struct change_info4 {
bool atomic; bool atomic;
changeid4 before; changeid4 before;
changeid4 after; changeid4 after;
}; };
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
This structure is used with the CREATE, LINK, REMOVE, RENAME This structure is used with the CREATE, LINK, REMOVE, RENAME
operations to let the client the know value of the change operations to let the client know the value of the change
attribute for the directory in which the target file system attribute for the directory in which the target file system
object resides. object resides.
clientaddr4 clientaddr4
struct clientaddr4 { struct clientaddr4 {
/* see struct rpcb in RFC 1833 */ /* see struct rpcb in RFC 1833 */
string r_netid<>; /* network id */ string r_netid<>; /* network id */
string r_addr<>; /* universal address */ string r_addr<>; /* universal address */
}; };
skipping to change at page 18, line 39 skipping to change at page 18, line 39
}; };
This structure is used by the client to inform the server of its This structure is used by the client to inform the server of its
call back address; includes the program number and client call back address; includes the program number and client
address. address.
nfs_client_id4 nfs_client_id4
struct nfs_client_id4 { struct nfs_client_id4 {
verifier4 verifier; verifier4 verifier;
opaque id<>; opaque id<NFS4_OPAQUE_LIMIT>;
}; };
This structure is part of the arguments to the SETCLIENTID This structure is part of the arguments to the SETCLIENTID
operation. operation. NFS4_OPAQUE_LIMIT is defined as 1024.
nfs_lockowner4 open_owner4
struct nfs_lockowner4 { struct open_owner4 {
clientid4 clientid; clientid4 clientid;
opaque owner<>; opaque owner<NFS4_OPAQUE_LIMIT>;
}; };
This structure is used to identify the owner of a OPEN share or This structure is used to identify the owner of open state.
file lock. NFS4_OPAQUE_LIMIT is defined as 1024.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
lock_owner4
struct nfs_lockowner4 {
clientid4 clientid;
opaque owner<NFS4_OPAQUE_LIMIT>;
};
This structure is used to identify the owner of file locking
state. NFS4_OPAQUE_LIMIT is defined as 1024.
stateid4 stateid4
struct stateid4 { struct stateid4 {
uint32_t seqid; uint32_t seqid;
opaque other[12]; opaque other[12];
}; };
This strucutre is used for the various state sharing mechanisms This strucutre is used for the various state sharing mechanisms
between the client and server. For the client, this data between the client and server. For the client, this data
structure is read-only. The seqid value is the only field that structure is read-only. The seqid value is the only field that
the client should interpret. See the section for the OPEN the client should interpret. See the section for the OPEN
operation for further description of how the seqid field is to operation for further description of how the seqid field is to
be interpreted. be interpreted.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
3. RPC and Security Flavor 3. RPC and Security Flavor
The NFS version 4 protocol is a Remote Procedure Call (RPC) The NFS version 4 protocol is a Remote Procedure Call (RPC)
application that uses RPC version 2 and the corresponding eXternal application that uses RPC version 2 and the corresponding eXternal
Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The Data Representation (XDR) as defined in [RFC1831] and [RFC1832]. The
RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as RPCSEC_GSS security flavor as defined in [RFC2203] MUST be used as
the mechanism to deliver stronger security for the NFS version 4 the mechanism to deliver stronger security for the NFS version 4
protocol. protocol.
skipping to change at page 21, line 5 skipping to change at page 21, line 5
of varying security mechanisms by the RPC layer without the of varying security mechanisms by the RPC layer without the
additional implementation overhead of adding RPC security flavors. additional implementation overhead of adding RPC security flavors.
For NFS version 4, the RPCSEC_GSS security flavor MUST be used to For NFS version 4, the RPCSEC_GSS security flavor MUST be used to
enable the mandatory security mechanism. Other flavors, such as, enable the mandatory security mechanism. Other flavors, such as,
AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well. AUTH_NONE, AUTH_SYS, and AUTH_DH MAY be implemented as well.
3.2.1. Security mechanisms for NFS version 4 3.2.1. Security mechanisms for NFS version 4
The use of RPCSEC_GSS requires selection of: mechanism, quality of The use of RPCSEC_GSS requires selection of: mechanism, quality of
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
protection, and service (authentication, integrity, privacy). The protection, and service (authentication, integrity, privacy). The
remainder of this document will refer to these three parameters of remainder of this document will refer to these three parameters of
the RPCSEC_GSS security as the security triple. the RPCSEC_GSS security as the security triple.
3.2.1.1. Kerberos V5 as security triple 3.2.1.1. Kerberos V5 as security triple
The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be The Kerberos V5 GSS-API mechanism as described in [RFC1964] MUST be
implemented and provide the following security triples. implemented and provide the following security triples.
skipping to change at page 22, line 5 skipping to change at page 22, line 5
1 2 3 4 5 1 2 3 4 5
----------------------------------------------------------------------- -----------------------------------------------------------------------
390006 lipkey 1.3.6.1.5.5.9 negotiated rpc_gss_svc_none 390006 lipkey 1.3.6.1.5.5.9 negotiated rpc_gss_svc_none
390007 lipkey-i 1.3.6.1.5.5.9 negotiated rpc_gss_svc_integrity 390007 lipkey-i 1.3.6.1.5.5.9 negotiated rpc_gss_svc_integrity
390008 lipkey-p 1.3.6.1.5.5.9 negotiated rpc_gss_svc_privacy 390008 lipkey-p 1.3.6.1.5.5.9 negotiated rpc_gss_svc_privacy
The mechanism algorithm is listed as "negotiated". This is because The mechanism algorithm is listed as "negotiated". This is because
LIPKEY is layered on SPKM-3 and in SPKM-3 [RFC2847] the LIPKEY is layered on SPKM-3 and in SPKM-3 [RFC2847] the
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
confidentiality and integrity algorithms are negotiated. Since confidentiality and integrity algorithms are negotiated. Since
SPKM-3 specifies HMAC-MD5 for integrity as MANDATORY, 128 bit SPKM-3 specifies HMAC-MD5 for integrity as MANDATORY, 128 bit
cast5CBC for confidentiality for privacy as MANDATORY, and further cast5CBC for confidentiality for privacy as MANDATORY, and further
specifies that HMAC-MD5 and cast5CBC MUST be listed first before specifies that HMAC-MD5 and cast5CBC MUST be listed first before
weaker algorithms, specifying "negotiated" in column 4 does not weaker algorithms, specifying "negotiated" in column 4 does not
impair interoperability. In the event an SPKM-3 peer does not impair interoperability. In the event an SPKM-3 peer does not
support the mandatory algorithms, the other peer is free to accept or support the mandatory algorithms, the other peer is free to accept or
reject the GSS-API context creation. reject the GSS-API context creation.
Because SPKM-3 negotiates the algorithms, subsequent calls to Because SPKM-3 negotiates the algorithms, subsequent calls to
LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality LIPKEY's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality
of protection value of 0 (zero). See section 5.2 of [RFC2025] for an of protection value of 0 (zero). See section 5.2 of [RFC2025] for an
explanation. explanation.
LIPKEY uses SPKM-3 to create a secure channel in which to pass a user LIPKEY uses SPKM-3 to create a secure channel in which to pass a user
name and password from the client to the user. Once the user name name and password from the client to the server. Once the user name
and password have been accepted by the server, calls to the LIPKEY and password have been accepted by the server, calls to the LIPKEY
context are redirected to the SPKM-3 context. See [RFC2847] for more context are redirected to the SPKM-3 context. See [RFC2847] for more
details. details.
3.2.1.3. SPKM-3 as a security triple 3.2.1.3. SPKM-3 as a security triple
The SPKM-3 GSS-API mechanism as described in [RFC2847] MUST be The SPKM-3 GSS-API mechanism as described in [RFC2847] MUST be
implemented and provide the following security triples. The implemented and provide the following security triples. The
definition of the columns matches the previous subsection "Kerberos definition of the columns matches the previous subsection "Kerberos
V5 as security triple". V5 as security triple".
skipping to change at page 23, line 5 skipping to change at page 23, line 5
explanation. explanation.
Even though LIPKEY is layered over SPKM-3, SPKM-3 is specified as a Even though LIPKEY is layered over SPKM-3, SPKM-3 is specified as a
mandatory set of triples to handle the situations where the initiator mandatory set of triples to handle the situations where the initiator
(the client) is anonymous or where the initiator has its own (the client) is anonymous or where the initiator has its own
certificate. If the initiator is anonymous, there will not be a user certificate. If the initiator is anonymous, there will not be a user
name and password to send to the target (the server). If the name and password to send to the target (the server). If the
initiator has its own certificate, then using passwords is initiator has its own certificate, then using passwords is
superfluous. superfluous.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
3.3. Security Negotiation 3.3. Security Negotiation
With the NFS version 4 server potentially offering multiple security With the NFS version 4 server potentially offering multiple security
mechanisms, the client needs a method to determine or negotiate which mechanisms, the client needs a method to determine or negotiate which
mechanism is to be used for its communication with the server. The mechanism is to be used for its communication with the server. The
NFS server may have multiple points within its file system name space NFS server may have multiple points within its file system name space
that are available for use by NFS clients. In turn the NFS server that are available for use by NFS clients. In turn the NFS server
may be configured such that each of these entry points may have may be configured such that each of these entry points may have
different or multiple security mechanisms in use. different or multiple security mechanisms in use.
skipping to change at page 24, line 5 skipping to change at page 24, line 5
The callback RPC (described later) must mutually authenticate the NFS The callback RPC (described later) must mutually authenticate the NFS
server to the principal that acquired the clientid (also described server to the principal that acquired the clientid (also described
later), using the same security flavor the original SETCLIENTID later), using the same security flavor the original SETCLIENTID
operation used. Because LIPKEY is layered over SPKM-3, it is operation used. Because LIPKEY is layered over SPKM-3, it is
permissible for the server to use SPKM-3 and not LIPKEY for the permissible for the server to use SPKM-3 and not LIPKEY for the
callback even if the client used LIPKEY for SETCLIENTID. callback even if the client used LIPKEY for SETCLIENTID.
For AUTH_NONE, there are no principals, so this is a non-issue. For AUTH_NONE, there are no principals, so this is a non-issue.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
For AUTH_SYS, the server simply uses the AUTH_SYS credential that the For AUTH_SYS, the server simply uses the AUTH_SYS credential that the
user used when it set up the delegation. user used when it set up the delegation.
For AUTH_DH, one commonly used convention is that the server uses the For AUTH_DH, one commonly used convention is that the server uses the
credential corresponding to this AUTH_DH principal: credential corresponding to this AUTH_DH principal:
unix.host@domain unix.host@domain
where host and domain are variables corresponding to the name of where host and domain are variables corresponding to the name of
skipping to change at page 25, line 5 skipping to change at page 25, line 5
be used. This effectively means that the client will use a be used. This effectively means that the client will use a
certificate to authenticate and identify the initiator to the target certificate to authenticate and identify the initiator to the target
on the NFS server. Using SPKM-3 and not LIPKEY has the following on the NFS server. Using SPKM-3 and not LIPKEY has the following
advantages: advantages:
o When the server does a callback, it must authenticate to the o When the server does a callback, it must authenticate to the
principal used in the SETCLIENTID. Even if LIPKEY is used, principal used in the SETCLIENTID. Even if LIPKEY is used,
because LIPKEY is layered over SPKM-3, the NFS client will need because LIPKEY is layered over SPKM-3, the NFS client will need
to have a certificate that corresponds to the principal used in to have a certificate that corresponds to the principal used in
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
the SETCLIENTID operation. From an administrative perspective, the SETCLIENTID operation. From an administrative perspective,
having a user name, password, and certificate for both the having a user name, password, and certificate for both the
client and server is redundant. client and server is redundant.
o LIPKEY was intended to minimize additional infrastructure o LIPKEY was intended to minimize additional infrastructure
requirements beyond a certificate for the target, and the requirements beyond a certificate for the target, and the
expectation is that existing password infrastructure can be expectation is that existing password infrastructure can be
leveraged for the initiator. In some environments, a per-host leveraged for the initiator. In some environments, a per-host
password does not exist yet. If certificates are used for any password does not exist yet. If certificates are used for any
per-host principals, then additional password infrastructure is per-host principals, then additional password infrastructure is
not needed. not needed.
o In cases when a host is both an NFS client and server, it can o In cases when a host is both an NFS client and server, it can
share the same per-host certificate. share the same per-host certificate.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
4. Filehandles 4. Filehandles
The filehandle in the NFS protocol is a per server unique identifier The filehandle in the NFS protocol is a per server unique identifier
for a file system object. The contents of the filehandle are opaque for a file system object. The contents of the filehandle are opaque
to the client. Therefore, the server is responsible for translating to the client. Therefore, the server is responsible for translating
the filehandle to an internal representation of the file system the filehandle to an internal representation of the file system
object. Since the filehandle is the client's reference to an object object. Since the filehandle is the client's reference to an object
and the client may cache this reference, the server SHOULD not reuse and the client may cache this reference, the server SHOULD not reuse
a filehandle for another file system object. If the server needs to a filehandle for another file system object. If the server needs to
skipping to change at page 27, line 5 skipping to change at page 27, line 5
4.1.1. Root Filehandle 4.1.1. Root Filehandle
The first of the special filehandles is the ROOT filehandle. The The first of the special filehandles is the ROOT filehandle. The
ROOT filehandle is the "conceptual" root of the file system name ROOT filehandle is the "conceptual" root of the file system name
space at the NFS server. The client uses or starts with the ROOT space at the NFS server. The client uses or starts with the ROOT
filehandle by employing the PUTROOTFH operation. The PUTROOTFH filehandle by employing the PUTROOTFH operation. The PUTROOTFH
operation instructs the server to set the "current" filehandle to the operation instructs the server to set the "current" filehandle to the
ROOT of the server's file tree. Once this PUTROOTFH operation is ROOT of the server's file tree. Once this PUTROOTFH operation is
used, the client can then traverse the entirety of the server's file used, the client can then traverse the entirety of the server's file
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
tree with the LOOKUP procedure. A complete discussion of the server tree with the LOOKUP procedure. A complete discussion of the server
name space is in the section "NFS Server Name Space". name space is in the section "NFS Server Name Space".
4.1.2. Public Filehandle 4.1.2. Public Filehandle
The second special filehandle is the PUBLIC filehandle. Unlike the The second special filehandle is the PUBLIC filehandle. Unlike the
ROOT filehandle, the PUBLIC filehandle may be bound or represent an ROOT filehandle, the PUBLIC filehandle may be bound or represent an
arbitrary file system object at the server. The server is arbitrary file system object at the server. The server is
responsible for this binding. It may be that the PUBLIC filehandle responsible for this binding. It may be that the PUBLIC filehandle
skipping to change at page 28, line 5 skipping to change at page 28, line 5
filehandle differently, a file attribute is defined which may be used filehandle differently, a file attribute is defined which may be used
by the client to determine the filehandle types being returned by the by the client to determine the filehandle types being returned by the
server. server.
4.2.1. General Properties of a Filehandle 4.2.1. General Properties of a Filehandle
The filehandle contains all the information the server needs to The filehandle contains all the information the server needs to
distinguish an individual file. To the client, the filehandle is distinguish an individual file. To the client, the filehandle is
opaque. The client stores filehandles for use in a later request and opaque. The client stores filehandles for use in a later request and
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
can compare two filehandles from the same server for equality by can compare two filehandles from the same server for equality by
doing a byte-by-byte comparison. However, the client MUST NOT doing a byte-by-byte comparison. However, the client MUST NOT
otherwise interpret the contents of filehandles. If two filehandles otherwise interpret the contents of filehandles. If two filehandles
from the same server are equal, they MUST refer to the same file. If from the same server are equal, they MUST refer to the same file. If
they are not equal, the client may use information provided by the they are not equal, the client may use information provided by the
server, in the form of file attributes, to determine whether they server, in the form of file attributes, to determine whether they
denote the same files or different files. The client would do this denote the same files or different files. The client would do this
as necessary for client side caching. Servers SHOULD try to maintain as necessary for client side caching. Servers SHOULD try to maintain
a one-to-one correspondence between filehandles and files but this is a one-to-one correspondence between filehandles and files but this is
skipping to change at page 29, line 5 skipping to change at page 29, line 5
file system containing the object is no longer available. The file file system containing the object is no longer available. The file
system may become unavailable if it exists on removable media and the system may become unavailable if it exists on removable media and the
media is no longer available at the server or the file system in media is no longer available at the server or the file system in
whole has been destroyed or the file system has simply been removed whole has been destroyed or the file system has simply been removed
from the server's name space (i.e. unmounted in a Unix environment). from the server's name space (i.e. unmounted in a Unix environment).
4.2.3. Volatile Filehandle 4.2.3. Volatile Filehandle
A volatile filehandle does not share the same longevity A volatile filehandle does not share the same longevity
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
characteristics of a persistent filehandle. The server may determine characteristics of a persistent filehandle. The server may determine
that a volatile filehandle is no longer valid at many different that a volatile filehandle is no longer valid at many different
points in time. If the server can definitively determine that a points in time. If the server can definitively determine that a
volatile filehandle refers to an object that has been removed, the volatile filehandle refers to an object that has been removed, the
server should return NFS4ERR_STALE to the client (as is the case for server should return NFS4ERR_STALE to the client (as is the case for
persistent filehandles). In all other cases where the server persistent filehandles). In all other cases where the server
determines that a volatile filehandle can no longer be used, it determines that a volatile filehandle can no longer be used, it
should return an error of NFS4ERR_FHEXPIRED. should return an error of NFS4ERR_FHEXPIRED.
skipping to change at page 30, line 5 skipping to change at page 30, line 5
REMOVE that would affect an OPEN file or any of the components REMOVE that would affect an OPEN file or any of the components
leading to the OPEN file. In addition, the server should deny all leading to the OPEN file. In addition, the server should deny all
RENAME or REMOVE requests during the grace or lease period upon RENAME or REMOVE requests during the grace or lease period upon
server restart. server restart.
The reader may be wondering why there are three FH4_VOL* bits and why The reader may be wondering why there are three FH4_VOL* bits and why
FH4_VOLATILE_ANY is exclusive of FH4_VOL_MIGRATION and FH4_VOLATILE_ANY is exclusive of FH4_VOL_MIGRATION and
FH4_VOL_RENAME. If the a filehandle is normally persistent but FH4_VOL_RENAME. If the a filehandle is normally persistent but
cannot persist across a file set migration, then the presence of the cannot persist across a file set migration, then the presence of the
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
FH4_VOL_MIGRATION or FH4_VOL_RENAME tells the client that it can FH4_VOL_MIGRATION or FH4_VOL_RENAME tells the client that it can
treat the file handle as persistent for purposes of maintaining a treat the file handle as persistent for purposes of maintaining a
file name to file handle cache, except for the specific event file name to file handle cache, except for the specific event
described by the bit. However, FH4_VOLATILE_ANY tells the client described by the bit. However, FH4_VOLATILE_ANY tells the client
that it should not maintain such a cache for unopened files. A that it should not maintain such a cache for unopened files. A
server MUST not present FH4_VOLATILE_ANY with FH4_VOL_MIGRATION or server MUST not present FH4_VOLATILE_ANY with FH4_VOL_MIGRATION or
FH4_VOL_RENAME as this will lead to confusion. FH4_VOLATILE_ANY FH4_VOL_RENAME as this will lead to confusion. FH4_VOLATILE_ANY
implies that the file handle will expire upon migration or rename, in implies that the file handle will expire upon migration or rename, in
addition to other events. addition to other events.
skipping to change at page 31, line 5 skipping to change at page 31, line 5
4.3. Client Recovery from Filehandle Expiration 4.3. Client Recovery from Filehandle Expiration
If possible, the client SHOULD recover from the receipt of an If possible, the client SHOULD recover from the receipt of an
NFS4ERR_FHEXPIRED error. The client must take on additional NFS4ERR_FHEXPIRED error. The client must take on additional
responsibility so that it may prepare itself to recover from the responsibility so that it may prepare itself to recover from the
expiration of a volatile filehandle. If the server returns expiration of a volatile filehandle. If the server returns
persistent filehandles, the client does not need these additional persistent filehandles, the client does not need these additional
steps. steps.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
For volatile filehandles, most commonly the client will need to store For volatile filehandles, most commonly the client will need to store
the component names leading up to and including the file system the component names leading up to and including the file system
object in question. With these names, the client should be able to object in question. With these names, the client should be able to
recover by finding a filehandle in the name space that is still recover by finding a filehandle in the name space that is still
available or by starting at the root of the server's file system name available or by starting at the root of the server's file system name
space. space.
If the expired filehandle refers to an object that has been removed If the expired filehandle refers to an object that has been removed
from the file system, obviously the client will not be able to from the file system, obviously the client will not be able to
skipping to change at page 32, line 5 skipping to change at page 32, line 5
the file is open, it is possible that the client may be able to the file is open, it is possible that the client may be able to
recover. The client can determine the new path name based on the recover. The client can determine the new path name based on the
processing of the rename request. The client can then regenerate the processing of the rename request. The client can then regenerate the
new filehandle based on the new path name. The client could also use new filehandle based on the new path name. The client could also use
the compound operation mechanism to construct a set of operations the compound operation mechanism to construct a set of operations
like: like:
RENAME A B RENAME A B
LOOKUP B LOOKUP B
GETFH GETFH
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
5. File Attributes 5. File Attributes
To meet the requirements of extensibility and increased To meet the requirements of extensibility and increased
interoperability with non-Unix platforms, attributes must be handled interoperability with non-Unix platforms, attributes must be handled
in a flexible manner. The NFS Version 3 fattr3 structure contains a in a flexible manner. The NFS Version 3 fattr3 structure contains a
fixed list of attributes that not all clients and servers are able to fixed list of attributes that not all clients and servers are able to
support or care about. The fattr3 structure can not be extended as support or care about. The fattr3 structure can not be extended as
new needs arise and it provides no way to indicate non-support. With new needs arise and it provides no way to indicate non-support. With
the NFS Version 4 protocol, the client will be able to ask what the NFS Version 4 protocol, the client will be able to ask what
skipping to change at page 33, line 5 skipping to change at page 33, line 5
encouraged to define their new attributes as recommended attributes encouraged to define their new attributes as recommended attributes
by bringing them to the IETF standards-track process. by bringing them to the IETF standards-track process.
The set of attributes which are classified as mandatory is The set of attributes which are classified as mandatory is
deliberately small since servers must do whatever it takes to support deliberately small since servers must do whatever it takes to support
them. The recommended attributes may be unsupported; though a server them. The recommended attributes may be unsupported; though a server
should support as many as it can. Attributes are deemed mandatory if should support as many as it can. Attributes are deemed mandatory if
the data is both needed by a large number of clients and is not the data is both needed by a large number of clients and is not
otherwise reasonably computable by the client when support is not otherwise reasonably computable by the client when support is not
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
provided on the server. provided on the server.
5.1. Mandatory Attributes 5.1. Mandatory Attributes
These MUST be supported by every NFS Version 4 client and server in These MUST be supported by every NFS Version 4 client and server in
order to ensure a minimum level of interoperability. The server must order to ensure a minimum level of interoperability. The server must
store and return these attributes and the client must be able to store and return these attributes and the client must be able to
function with an attribute set limited to these attributes. With function with an attribute set limited to these attributes. With
just the mandatory attributes some client functionality may be just the mandatory attributes some client functionality may be
skipping to change at page 34, line 5 skipping to change at page 34, line 5
OPENATTR operation returns a filehandle for a virtual "attribute OPENATTR operation returns a filehandle for a virtual "attribute
directory" and further perusal of the name space may be done using directory" and further perusal of the name space may be done using
READDIR and LOOKUP operations on this filehandle. Named attributes READDIR and LOOKUP operations on this filehandle. Named attributes
may then be examined or changed by normal READ and WRITE and CREATE may then be examined or changed by normal READ and WRITE and CREATE
operations on the filehandles returned from READDIR and LOOKUP. operations on the filehandles returned from READDIR and LOOKUP.
Named attributes may have attributes. Named attributes may have attributes.
It is recommended that servers support arbitrary named attributes. A It is recommended that servers support arbitrary named attributes. A
client should not depend on the ability to store any named attributes client should not depend on the ability to store any named attributes
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
in the server's file system. If a server does support named in the server's file system. If a server does support named
attributes, a client which is also able to handle them should be able attributes, a client which is also able to handle them should be able
to copy a file's data and meta-data with complete transparency from to copy a file's data and meta-data with complete transparency from
one location to another; this would imply that names allowed for one location to another; this would imply that names allowed for
regular directory entries are valid for named attribute names as regular directory entries are valid for named attribute names as
well. well.
Names of attributes will not be controlled by this document or other Names of attributes will not be controlled by this document or other
IETF standards track documents. See the section "IANA IETF standards track documents. See the section "IANA
Considerations" for further discussion. Considerations" for further discussion.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
5.4. Mandatory Attributes - Definitions 5.4. Mandatory Attributes - Definitions
Name # DataType Access Description Name # DataType Access Description
___________________________________________________________________ ___________________________________________________________________
supp_attr 0 bitmap READ The bit vector which supp_attr 0 bitmap READ
The bit vector which
would retrieve all would retrieve all
mandatory and mandatory and
recommended attributes recommended attributes
that are supported for that are supported for
this object. this object.
type 1 nfs4_ftype READ The type of the object type 1 nfs4_ftype READ
The type of the object
(file, directory, (file, directory,
symlink) symlink)
fh_expire_type 2 uint32 READ Server uses this to fh_expire_type 2 uint32 READ
Server uses this to
specify filehandle specify filehandle
expiration behavior to expiration behavior to
the client. See the the client. See the
section "Filehandles" section "Filehandles"
for additional for additional
description. description.
change 3 uint64 READ A value created by the change 3 uint64 READ
A value created by the
server that the client server that the client
can use to determine can use to determine
if file data, if file data,
directory contents or directory contents or
attributes of the attributes of the
object have been object have been
modified. The server modified. The server
may return the may return the
object's time_modify object's time_modify
attribute for this attribute for this
attribute's value but attribute's value but
only if the file only if the file
system object can not system object can not
be updated more be updated more
frequently than the frequently than the
resolution of resolution of
time_modify. time_modify.
size 4 uint64 R/W The size of the object size 4 uint64 R/W
The size of the object
in bytes. in bytes.
link_support 5 bool READ Does the object's file link_support 5 bool READ
Does the object's file
system supports hard system supports hard
links? links?
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
symlink_support 6 bool READ Does the object's file symlink_support 6 bool READ
Does the object's file
system supports system supports
symbolic links? symbolic links?
named_attr 7 bool READ Does this object have named_attr 7 bool READ
Does this object have
named attributes? named attributes?
fsid 8 fsid4 READ Unique file system fsid 8 fsid4 READ
Unique file system
identifier for the identifier for the
file system holding file system holding
this object. fsid this object. fsid
contains major and contains major and
minor components each minor components each
of which are uint64. of which are uint64.
unique_handles 9 bool READ Are two distinct unique_handles 9 bool READ
Are two distinct
filehandles guaranteed filehandles guaranteed
to refer to two to refer to two
different file system different file system
objects? objects?
lease_time 10 nfs_lease4 READ Duration of leases at lease_time 10 nfs_lease4 READ
Duration of leases at
server in seconds. server in seconds.
rdattr_error 11 enum READ Error returned from rdattr_error 11 enum READ
Error returned from
getattr during getattr during
readdir. readdir.
filehandle 19 nfs_fh4 READ The filehandle of this filehandle 19 nfs_fh4 READ
The filehandle of this
object (primarily for object (primarily for
readdir requests). readdir requests).
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
5.5. Recommended Attributes - Definitions 5.5. Recommended Attributes - Definitions
Name # Data Type Access Description Name # Data Type Access Description
_____________________________________________________________________ _____________________________________________________________________
ACL 12 nfsace4<> R/W The access control ACL 12 nfsace4<> R/W
The access control
list for the object. list for the object.
aclsupport 13 uint32 READ Indicates what types aclsupport 13 uint32 READ
Indicates what types
of ACLs are supported of ACLs are supported
on the current file on the current file
system. system.
archive 14 bool R/W Whether or not this archive 14 bool R/W
Whether or not this
file has been file has been
archived since the archived since the
time of last time of last
modification modification
(deprecated in favor (deprecated in favor
of time_backup). of time_backup).
cansettime 15 bool READ Is the server able to cansettime 15 bool READ
Is the server able to
change the times for change the times for
a file system object a file system object
as specified in a as specified in a
SETATTR operation? SETATTR operation?
case_insensitive 16 bool READ Are filename case_insensitive 16 bool READ
Are filename
comparisons on this comparisons on this
file system case file system case
insensitive? insensitive?
case_preserving 17 bool READ Is filename case on case_preserving 17 bool READ
Is filename case on
this file system this file system
preserved? preserved?
chown_restricted 18 bool READ If TRUE, the server chown_restricted 18 bool READ
If TRUE, the server
will reject any will reject any
request to change request to change
either the owner or either the owner or
the group associated the group associated
with a file if the with a file if the
caller is not a caller is not a
privileged user (for privileged user (for
example, "root" in example, "root" in
Unix operating Unix operating
environments or in NT environments or in NT
the "Take Ownership" the "Take Ownership"
privilege) privilege)
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
fileid 20 uint64 READ A number uniquely fileid 20 uint64 READ
A number uniquely
identifying the file identifying the file
within the file within the file
system. system.
files_avail 21 uint64 READ File slots available files_avail 21 uint64 READ
File slots available
to this user on the to this user on the
file system file system
containing this containing this
object - this should object - this should
be the smallest be the smallest
relevant limit. relevant limit.
files_free 22 uint64 READ Free file slots on files_free 22 uint64 READ
Free file slots on
the file system the file system
containing this containing this
object - this should object - this should
be the smallest be the smallest
relevant limit. relevant limit.
files_total 23 uint64 READ Total file slots on files_total 23 uint64 READ
Total file slots on
the file system the file system
containing this containing this
object. object.
fs_locations 24 fs_locations READ Locations where this fs_locations 24 fs_locations READ
Locations where this
file system may be file system may be
found. If the server found. If the server
returns NFS4ERR_MOVED returns NFS4ERR_MOVED
as an error, this as an error, this
attribute must be attribute must be
supported. supported.
hidden 25 bool R/W Is file considered hidden 25 bool R/W
Is file considered
hidden with respect hidden with respect
to the WIN32 API? to the WIN32 API?
homogeneous 26 bool READ Whether or not this homogeneous 26 bool READ
Whether or not this
object's file system object's file system
is homogeneous, i.e. is homogeneous, i.e.
are per file system are per file system
attributes the same attributes the same
for all file system's for all file system's
objects. objects.
maxfilesize 27 uint64 READ Maximum supported maxfilesize 27 uint64 READ
Maximum supported
file size for the file size for the
file system of this file system of this
object. object.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
maxlink 28 uint32 READ Maximum number of maxlink 28 uint32 READ
Maximum number of
links for this links for this
object. object.
maxname 29 uint32 READ Maximum filename size maxname 29 uint32 READ
Maximum filename size
supported for this supported for this
object. object.
maxread 30 uint64 READ Maximum read size maxread 30 uint64 READ
Maximum read size
supported for this supported for this
object. object.
maxwrite 31 uint64 READ Maximum write size maxwrite 31 uint64 READ
Maximum write size
supported for this supported for this
object. This object. This
attribute SHOULD be attribute SHOULD be
supported if the file supported if the file
is writable. Lack of is writable. Lack of
this attribute can this attribute can
lead to the client lead to the client
either wasting either wasting
bandwidth or not bandwidth or not
receiving the best receiving the best
performance. performance.
mimetype 32 utf8<> R/W MIME body mimetype 32 utf8<> R/W
MIME body
type/subtype of this type/subtype of this
object. object.
mode 33 mode4 R/W Unix-style permission mode 33 mode4 R/W
Unix-style permission
bits for this object bits for this object
(deprecated in favor (deprecated in favor
of ACLs) of ACLs)
no_trunc 34 bool READ If a name longer than no_trunc 34 bool READ
If a name longer than
name_max is used, name_max is used,
will an error be will an error be
returned or will the returned or will the
name be truncated? name be truncated?
numlinks 35 uint32 READ Number of hard links numlinks 35 uint32 READ
Number of hard links
to this object. to this object.
owner 36 utf8<> R/W The string name of owner 36 utf8<> R/W
The string name of
the owner of this the owner of this
object. object.
owner_group 37 utf8<> R/W The string name of owner_group 37 utf8<> R/W
The string name of
the group ownership the group ownership
of this object. of this object.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
quota_avail_hard 38 uint64 READ For definition see quota_avail_hard 38 uint64 READ
For definition see
"Quota Attributes" "Quota Attributes"
section below. section below.
quota_avail_soft 39 uint64 READ For definition see quota_avail_soft 39 uint64 READ
For definition see
"Quota Attributes" "Quota Attributes"
section below. section below.
quota_used 40 uint64 READ For definition see quota_used 40 uint64 READ
For definition see
"Quota Attributes" "Quota Attributes"
section below. section below.
rawdev 41 specdata4 READ Raw device rawdev 41 specdata4 READ
Raw device
identifier. Unix identifier. Unix
device major/minor device major/minor
node information. node information.
space_avail 42 uint64 READ Disk space in bytes space_avail 42 uint64 READ
Disk space in bytes
available to this available to this
user on the file user on the file
system containing system containing
this object - this this object - this
should be the should be the
smallest relevant smallest relevant
limit. limit.
space_free 43 uint64 READ Free disk space in space_free 43 uint64 READ
Free disk space in
bytes on the file bytes on the file
system containing system containing
this object - this this object - this
should be the should be the
smallest relevant smallest relevant
limit. limit.
space_total 44 uint64 READ Total disk space in space_total 44 uint64 READ
Total disk space in
bytes on the file bytes on the file
system containing system containing
this object. this object.
space_used 45 uint64 READ Number of file system space_used 45 uint64 READ
Number of file system
bytes allocated to bytes allocated to
this object. this object.
system 46 bool R/W Is this file a system system 46 bool R/W
Is this file a system
file with respect to file with respect to
the WIN32 API? the WIN32 API?
time_access 47 nfstime4 READ The time of last time_access 47 nfstime4 READ
The time of last
access to the object. access to the object.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
time_access_set 48 settime4 WRITE Set the time of last time_access_set 48 settime4 WRITE
Set the time of last
access to the object. access to the object.
SETATTR use only. SETATTR use only.
time_backup 49 nfstime4 R/W The time of last time_backup 49 nfstime4 R/W
The time of last
backup of the object. backup of the object.
time_create 50 nfstime4 R/W The time of creation time_create 50 nfstime4 R/W
The time of creation
of the object. This of the object. This
attribute does not attribute does not
have any relation to have any relation to
the traditional Unix the traditional Unix
file attribute file attribute
"ctime" or "change "ctime" or "change
time". time".
time_delta 51 nfstime4 READ Smallest useful time_delta 51 nfstime4 READ
Smallest useful
server time server time
granularity. granularity.
time_metadata 52 nfstime4 R/W The time of last time_metadata 52 nfstime4 R/W
The time of last
meta-data meta-data
modification of the modification of the
object. object.
time_modify 53 nfstime4 READ The time of last time_modify 53 nfstime4 READ
The time of last
modification to the modification to the
object. object.
time_modify_set 54 settime4 WRITE Set the time of last time_modify_set 54 settime4 WRITE
Set the time of last
modification to the modification to the
object. SETATTR use object. SETATTR use
only. only.
5.6. Interpreting owner and owner_group 5.6. Interpreting owner and owner_group
The recommended attributes "owner" and "owner_group" are represented The recommended attributes "owner" and "owner_group" (and also users
in terms of a UTF-8 string. To avoid a representation that is tied and groups within the "acl" attribute) are represented in terms of a
to a particular underlying implementation at the client or server, UTF-8 string. To avoid a representation that is tied to a particular
the use of the UTF-8 string has been chosen. Note that section 6.1 underlying implementation at the client or server, the use of the
of [RFC2624] provides additional rationale. It is expected that the UTF-8 string has been chosen. Note that section 6.1 of [RFC2624]
client and server will have their own local representation of owner provides additional rationale. It is expected that the client and
and owner_group that is used for local storage or presentation to the server will have their own local representation of owner and
end user. Therefore, it is expected that when these attributes are owner_group that is used for local storage or presentation to the end
user. Therefore, it is expected that when these attributes are
transferred between the client and server that the local transferred between the client and server that the local
representation is translated to a syntax of the form representation is translated to a syntax of the form
"user@dns_domain". This will allow for a client and server that do "user@dns_domain". This will allow for a client and server that do
not use the same local representation the ability to translate to a not use the same local representation the ability to translate to a
common syntax that can be interpreted by both. common syntax that can be interpreted by both.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
The translation is not specified as part of the protocol. This Similarly, security principals may be represented in different ways
allows various solutions to be employed. For example, a local by different security mechanisms. Servers normally translate these
translation table may be consulted that maps between a numeric id to representations into a common format, generally that used by local
the user@dns_domain syntax. A name service may also be used to storage, to serve as a means of identifying the users corresponding
accomplish the translation. The "dns_domain" portion of the owner to these security principals. When these local identifiers are
string is meant to be a DNS domain name. For example, user@ietf.org. translated to the form of the owner attribute, associated with files
created by such principals they identify, in a common format, the
users associated with each corresponding set of security principals.
The translation used to interpret owner and group strings is not
specified as part of the protocol. This allows various solutions to
be employed. For example, a local translation table may be consulted
that maps between a numeric id to the user@dns_domain syntax. A name
service may also be used to accomplish the translation. A server may
provide a more general service, not limited by any particular
translation (which would only translate a limited set of possible
strings) by storing the owner and owner_group attributes in local
storage without any translation or it may augment a translation
method by storing the entire string for attributes for which no
translation is available while using the local representation for
those cases in which a translation is available.
Servers that do not provide support for all possible values of the
owner and owner_group attributes, should return an error
(NFS4ERR_BADOWNER) when a string is presented that has no
translation, as the value to be set for a SETATTR of the owner,
owner_group, or acl attributes. When a server does accept an owner
or owner_group value as valid on a SETATTR (and similarly for the
owner and group strings in an acl), it is promising to return that
same string when a corresponding GETATTR is done. Configuration
changes and ill-constructed name translations (those that contain
aliasing) may make that promise impossible to honor. Servers should
make appropriate efforts to avoid a situation in which these
attributes have their values changed when no real change to ownership
has occurred.
The "dns_domain" portion of the owner string is meant to be a DNS
domain name. For example, user@ietf.org. Servers should accept as
valid a set of users for at least one domain. A server may treat
other domains as having no valid translations. A more general
service is provided when a server is capable of accepting users for
multiple domains, or for all domains, subject to security
constraints.
In the case where there is no translation available to the client or In the case where there is no translation available to the client or
server, the attribute value must be constructed without the "@". server, the attribute value must be constructed without the "@".
Therefore, the absence of the @ from the owner or owner_group Therefore, the absence of the @ from the owner or owner_group
attribute signifies that no translation was available and the attribute signifies that no translation was available at the sender
receiver of the attribute should not place any special meaning with and that the receiver of the attribute should not use that string as
the attribute value. Even though the attribute value can not be a basis for translation into its own internal format. Even though
translated, it may still be useful. In the case of a client, the the attribute value can not be translated, it may still be useful.
attribute string may be used for local display of ownership. In the case of a client, the attribute string may be used for local
Draft Specification NFS version 4 Protocol July 2002
display of ownership.
To provide a greater degree of compatibility with previous versions
of NFS (i.e. v2 and v3), which identified users and groups by 32-bit
unsigned uid's and gid's, owner and group strings that consist of
decimal numeric values with no leading zeros can be given a special
interpretation by clients and servers which choose to provide such
support. The receiver may treat such a user or group string as
representing the same user as would be represented by a v2/v3 uid or
gid having the corresponding numeric value. A server is not
obligated to accept such a string, but may return an NFS4ERR_BADOWNER
instead. To avoid this mechanism being used to subvert user and
group translation, so that a client might pass all of the owners and
groups in numeric form, a server SHOULD return an NFS4ERR_BADOWNER
error when there is a valid translation for the user or owner
designated in this way. In that case, the client must use the
appropriate name@domain string and not the special form for
compatibility.
The owner string "nobody" may be used to designate an anonymous user,
which will be associated with a file created by a security principal
that cannot be mapped through normal means to the owner attribute.
5.7. Character Case Attributes 5.7. Character Case Attributes
With respect to the case_insensitive and case_preserving attributes, With respect to the case_insensitive and case_preserving attributes,
each UCS-4 character (which UTF-8 encodes) has a "long descriptive each UCS-4 character (which UTF-8 encodes) has a "long descriptive
name" [RFC1345] which may or may not included the word "CAPITAL" or name" [RFC1345] which may or may not included the word "CAPITAL" or
"SMALL". The presence of SMALL or CAPITAL allows an NFS server to "SMALL". The presence of SMALL or CAPITAL allows an NFS server to
implement unambiguous and efficient table driven mappings for case implement unambiguous and efficient table driven mappings for case
insensitive comparisons, and non-case-preserving storage. For insensitive comparisons, and non-case-preserving storage. For
general character handling and internationalization issues, see the general character handling and internationalization issues, see the
skipping to change at page 42, line 49 skipping to change at page 44, line 4
quota_avail_soft quota_avail_soft
The value in bytes which represents the amount of additional The value in bytes which represents the amount of additional
disk space that can be allocated to this file or directory disk space that can be allocated to this file or directory
before the user may reasonably be warned. It is understood that before the user may reasonably be warned. It is understood that
this space may be consumed by allocations to other files or this space may be consumed by allocations to other files or
directories though there is a rule as to which other files or directories though there is a rule as to which other files or
directories. directories.
quota_avail_hard quota_avail_hard
The value in bytes which represent the amount of additional disk The value in bytes which represent the amount of additional disk
Draft Specification NFS version 4 Protocol July 2002
space beyond the current allocation that can be allocated to space beyond the current allocation that can be allocated to
this file or directory before further allocations will be this file or directory before further allocations will be
refused. It is understood that this space may be consumed by refused. It is understood that this space may be consumed by
allocations to other files or directories. allocations to other files or directories.
quota_used quota_used
Draft Specification NFS version 4 Protocol November 2001
The value in bytes which represent the amount of disc space used The value in bytes which represent the amount of disc space used
by this file or directory and possibly a number of other similar by this file or directory and possibly a number of other similar
files or directories, where the set of "similar" meets at least files or directories, where the set of "similar" meets at least
the criterion that allocating space to any file or directory in the criterion that allocating space to any file or directory in
the set will reduce the "quota_avail_hard" of every other file the set will reduce the "quota_avail_hard" of every other file
or directory in the set. or directory in the set.
Note that there may be a number of distinct but overlapping sets Note that there may be a number of distinct but overlapping sets
of files or directories for which a quota_used value is of files or directories for which a quota_used value is
maintained. E.g. "all files with a given owner", "all files with maintained. E.g. "all files with a given owner", "all files with
skipping to change at page 43, line 33 skipping to change at page 44, line 39
5.9. Access Control Lists 5.9. Access Control Lists
The NFS ACL attribute is an array of access control entries (ACE). The NFS ACL attribute is an array of access control entries (ACE).
There are various access control entry types. The server is able to There are various access control entry types. The server is able to
communicate which ACE types are supported by returning the communicate which ACE types are supported by returning the
appropriate value within the aclsupport attribute. The types of ACEs appropriate value within the aclsupport attribute. The types of ACEs
are defined as follows: are defined as follows:
Type Description Type Description
_____________________________________________________ _____________________________________________________
ALLOW Explicitly grants the access defined in ALLOW
Explicitly grants the access defined in
acemask4 to the file or directory. acemask4 to the file or directory.
DENY Explicitly denies the access defined in DENY
Explicitly denies the access defined in
acemask4 to the file or directory. acemask4 to the file or directory.
AUDIT LOG (system dependent) any access AUDIT
LOG (system dependent) any access
attempt to a file or directory which attempt to a file or directory which
uses any of the access methods specified uses any of the access methods specified
in acemask4. in acemask4.
ALARM Generate a system ALARM (system ALARM
Generate a system ALARM (system
dependent) when any access attempt is dependent) when any access attempt is
made to a file or directory for the made to a file or directory for the
access methods specified in acemask4. access methods specified in acemask4.
The NFS ACE attribute is defined as follows: The NFS ACE attribute is defined as follows:
Draft Specification NFS version 4 Protocol July 2002
typedef uint32_t acetype4; typedef uint32_t acetype4;
typedef uint32_t aceflag4; typedef uint32_t aceflag4;
typedef uint32_t acemask4; typedef uint32_t acemask4;
struct nfsace4 { struct nfsace4 {
acetype4 type; acetype4 type;
aceflag4 flag; aceflag4 flag;
Draft Specification NFS version 4 Protocol November 2001
acemask4 access_mask; acemask4 access_mask;
utf8string who; utf8string who;
}; };
To determine if an ACCESS or OPEN request succeeds each nfsace4 entry To determine if an ACCESS or OPEN request succeeds each nfsace4 entry
is processed in order by the server. Only ACEs which have a "who" is processed in order by the server. Only ACEs which have a "who"
that matches the requester are considered. Each ACE is processed that matches the requester are considered. Each ACE is processed
until all of the bits of the requester's access have been ALLOWED. until all of the bits of the requester's access have been ALLOWED.
Once a bit (see below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it Once a bit (see below) has been ALLOWED by an ACCESS_ALLOWED_ACE, it
is no longer considered in the processing of later ACEs. If an is no longer considered in the processing of later ACEs. If an
skipping to change at page 44, line 50 skipping to change at page 46, line 5
5.9.2. ACE flag 5.9.2. ACE flag
The "flag" field contains values based on the following descriptions. The "flag" field contains values based on the following descriptions.
ACE4_FILE_INHERIT_ACE ACE4_FILE_INHERIT_ACE
Can be placed on a directory and indicates that this ACE should be Can be placed on a directory and indicates that this ACE should be
added to each new non-directory file created. added to each new non-directory file created.
Draft Specification NFS version 4 Protocol July 2002
ACE4_DIRECTORY_INHERIT_ACE ACE4_DIRECTORY_INHERIT_ACE
Can be placed on a directory and indicates that this ACE should be Can be placed on a directory and indicates that this ACE should be
added to each new directory created. added to each new directory created.
Draft Specification NFS version 4 Protocol November 2001
ACE4_INHERIT_ONLY_ACE ACE4_INHERIT_ONLY_ACE
Can be placed on a directory but does not apply to the directory, Can be placed on a directory but does not apply to the directory,
only to newly created files/directories as specified by the above two only to newly created files/directories as specified by the above two
flags. flags.
ACE4_NO_PROPAGATE_INHERIT_ACE ACE4_NO_PROPAGATE_INHERIT_ACE
Can be placed on a directory. Normally when a new directory is Can be placed on a directory. Normally when a new directory is
created and an ACE exists on the parent directory which is marked created and an ACE exists on the parent directory which is marked
skipping to change at page 45, line 48 skipping to change at page 47, line 4
ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS ACE4_FAILED_ACCESS_ACE_FLAG causes the ALARM or AUDIT if the ACCESS
or OPEN call fails. or OPEN call fails.
ACE4_IDENTIFIER_GROUP ACE4_IDENTIFIER_GROUP
Indicates that the "who" refers to a GROUP as defined under Unix. Indicates that the "who" refers to a GROUP as defined under Unix.
The bitmask constants used for the flag field are as follows: The bitmask constants used for the flag field are as follows:
const ACE4_FILE_INHERIT_ACE = 0x00000001; const ACE4_FILE_INHERIT_ACE = 0x00000001;
Draft Specification NFS version 4 Protocol July 2002
const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002; const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004; const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
const ACE4_INHERIT_ONLY_ACE = 0x00000008; const ACE4_INHERIT_ONLY_ACE = 0x00000008;
const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010; const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020; const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
const ACE4_IDENTIFIER_GROUP = 0x00000040; const ACE4_IDENTIFIER_GROUP = 0x00000040;
Draft Specification NFS version 4 Protocol November 2001
5.9.3. ACE Access Mask 5.9.3. ACE Access Mask
The access_mask field contains values based on the following: The access_mask field contains values based on the following:
Access Description Access Description
_______________________________________________________________ _______________________________________________________________
READ_DATA Permission to read the data of the file READ_DATA
LIST_DIRECTORY Permission to list the contents of a Permission to read the data of the file
LIST_DIRECTORY
Permission to list the contents of a
directory directory
WRITE_DATA Permission to modify the file's data WRITE_DATA
ADD_FILE Permission to add a new file to a Permission to modify the file's data
ADD_FILE
Permission to add a new file to a
directory directory
APPEND_DATA Permission to append data to a file APPEND_DATA
ADD_SUBDIRECTORY Permission to create a subdirectory to a Permission to append data to a file
ADD_SUBDIRECTORY
Permission to create a subdirectory to a
directory directory
READ_NAMED_ATTRS Permission to read the named attributes READ_NAMED_ATTRS
Permission to read the named attributes
of a file of a file
WRITE_NAMED_ATTRS Permission to write the named attributes WRITE_NAMED_ATTRS
Permission to write the named attributes
of a file of a file
EXECUTE Permission to execute a file EXECUTE
DELETE_CHILD Permission to delete a file or directory Permission to execute a file
DELETE_CHILD
Permission to delete a file or directory
within a directory within a directory
READ_ATTRIBUTES The ability to read basic attributes READ_ATTRIBUTES
The ability to read basic attributes
(non-acls) of a file (non-acls) of a file
WRITE_ATTRIBUTES Permission to change basic attributes WRITE_ATTRIBUTES
Permission to change basic attributes
(non-acls) of a file (non-acls) of a file
DELETE Permission to Delete the file DELETE
READ_ACL Permission to Read the ACL Permission to Delete the file
WRITE_ACL Permission to Write the ACL READ_ACL
WRITE_OWNER Permission to change the owner Permission to Read the ACL
SYNCHRONIZE Permission to access file locally at the WRITE_ACL
Permission to Write the ACL
WRITE_OWNER
Permission to change the owner
SYNCHRONIZE
Permission to access file locally at the
server with synchronous reads and writes server with synchronous reads and writes
The bitmask constants used for the access mask field are as follows: The bitmask constants used for the access mask field are as follows:
const ACE4_READ_DATA = 0x00000001; const ACE4_READ_DATA = 0x00000001;
const ACE4_LIST_DIRECTORY = 0x00000001; const ACE4_LIST_DIRECTORY = 0x00000001;
const ACE4_WRITE_DATA = 0x00000002; const ACE4_WRITE_DATA = 0x00000002;
const ACE4_ADD_FILE = 0x00000002; const ACE4_ADD_FILE = 0x00000002;
const ACE4_APPEND_DATA = 0x00000004; const ACE4_APPEND_DATA = 0x00000004;
const ACE4_ADD_SUBDIRECTORY = 0x00000004; const ACE4_ADD_SUBDIRECTORY = 0x00000004;
const ACE4_READ_NAMED_ATTRS = 0x00000008; const ACE4_READ_NAMED_ATTRS = 0x00000008;
Draft Specification NFS version 4 Protocol July 2002
const ACE4_WRITE_NAMED_ATTRS = 0x00000010; const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
const ACE4_EXECUTE = 0x00000020; const ACE4_EXECUTE = 0x00000020;
const ACE4_DELETE_CHILD = 0x00000040; const ACE4_DELETE_CHILD = 0x00000040;
const ACE4_READ_ATTRIBUTES = 0x00000080; const ACE4_READ_ATTRIBUTES = 0x00000080;
const ACE4_WRITE_ATTRIBUTES = 0x00000100; const ACE4_WRITE_ATTRIBUTES = 0x00000100;
const ACE4_DELETE = 0x00010000; const ACE4_DELETE = 0x00010000;
const ACE4_READ_ACL = 0x00020000; const ACE4_READ_ACL = 0x00020000;
Draft Specification NFS version 4 Protocol November 2001
const ACE4_WRITE_ACL = 0x00040000; const ACE4_WRITE_ACL = 0x00040000;
const ACE4_WRITE_OWNER = 0x00080000; const ACE4_WRITE_OWNER = 0x00080000;
const ACE4_SYNCHRONIZE = 0x00100000; const ACE4_SYNCHRONIZE = 0x00100000;
5.9.4. ACE who 5.9.4. ACE who
There are several special identifiers ("who") which need to be There are several special identifiers ("who") which need to be
understood universally. Some of these identifiers cannot be understood universally. Some of these identifiers cannot be
understood when an NFS client accesses the server, but have meaning understood when an NFS client accesses the server, but have meaning
when a local process accesses the file. The ability to display and when a local process accesses the file. The ability to display and
modify these permissions is permitted over NFS. modify these permissions is permitted over NFS.
Who Description Who Description
_______________________________________________________________ _______________________________________________________________
"OWNER" The owner of the file. "OWNER"
"GROUP" The group associated with the file. The owner of the file.
"EVERYONE" The world. "GROUP"
"INTERACTIVE" Accessed from an interactive terminal. The group associated with the file.
"NETWORK" Accessed via the network. "EVERYONE"
"DIALUP" Accessed as a dialup user to the server. The world.
"BATCH" Accessed from a batch job. "INTERACTIVE"
"ANONYMOUS" Accessed without any authentication. Accessed from an interactive terminal.
"AUTHENTICATED" Any authenticated user (opposite of "NETWORK"
Accessed via the network.
"DIALUP"
Accessed as a dialup user to the server.
"BATCH"
Accessed from a batch job.
"ANONYMOUS"
Accessed without any authentication.
"AUTHENTICATED"
Any authenticated user (opposite of
ANONYMOUS) ANONYMOUS)
"SERVICE" Access from a system service. "SERVICE"
Access from a system service.
To avoid conflict, these special identifiers are distinguish by an To avoid conflict, these special identifiers are distinguish by an
appended "@" and should appear in the form "xxxx@" (note: no domain appended "@" and should appear in the form "xxxx@" (note: no domain
name after the "@"). For example: ANONYMOUS@. name after the "@"). For example: ANONYMOUS@.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
6. File System Migration and Replication 6. File System Migration and Replication
With the use of the recommended attribute "fs_locations", the NFS With the use of the recommended attribute "fs_locations", the NFS
version 4 server has a method of providing file system migration or version 4 server has a method of providing file system migration or
replication services. For the purposes of migration and replication, replication services. For the purposes of migration and replication,
a file system will be defined as all files that share a given fsid a file system will be defined as all files that share a given fsid
(both major and minor values are the same). (both major and minor values are the same).
The fs_locations attribute provides a list of file system locations. The fs_locations attribute provides a list of file system locations.
skipping to change at page 48, line 52 skipping to change at page 49, line 52
writable and has a single copy. The expected use of migration is for writable and has a single copy. The expected use of migration is for
load balancing or general resource reallocation. The protocol does load balancing or general resource reallocation. The protocol does
not specify how the file system will be moved between servers. This not specify how the file system will be moved between servers. This
server-to-server transfer mechanism is left to the server server-to-server transfer mechanism is left to the server
implementor. However, the method used to communicate the migration implementor. However, the method used to communicate the migration
event between client and server is specified here. event between client and server is specified here.
Once the servers participating in the migration have completed the Once the servers participating in the migration have completed the
move of the file system, the error NFS4ERR_MOVED will be returned for move of the file system, the error NFS4ERR_MOVED will be returned for
subsequent requests received by the original server. The subsequent requests received by the original server. The
NFS4ERR_MOVED error is returned for all operations except GETATTR. NFS4ERR_MOVED error is returned for all operations except PUTFH and
Upon receiving the NFS4ERR_MOVED error, the client will obtain the GETATTR. Upon receiving the NFS4ERR_MOVED error, the client will
value of the fs_locations attribute. The client will then use the obtain the value of the fs_locations attribute. The client will then
contents of the attribute to redirect its requests to the specified use the contents of the attribute to redirect its requests to the
server. To facilitate the use of GETATTR, operations such as PUTFH specified server. To facilitate the use of GETATTR, operations such
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
must also be accepted by the server for the migrated file system's as PUTFH must also be accepted by the server for the migrated file
filehandles. Note that if the server returns NFS4ERR_MOVED, the system's filehandles. Note that if the server returns NFS4ERR_MOVED,
server MUST support the fs_locations attribute. the server MUST support the fs_locations attribute.
If the client requests more attributes than just fs_locations, the If the client requests more attributes than just fs_locations, the
server may return fs_locations only. This is to be expected since server may return fs_locations only. This is to be expected since
the server has migrated the file system and may not have a method of the server has migrated the file system and may not have a method of
obtaining additional attribute data. obtaining additional attribute data.
The server implementor needs to be careful in developing a migration The server implementor needs to be careful in developing a migration
solution. The server must consider all of the state information solution. The server must consider all of the state information
clients may have outstanding at the server. This includes but is not clients may have outstanding at the server. This includes but is not
limited to locking/share state, delegation state, and asynchronous limited to locking/share state, delegation state, and asynchronous
skipping to change at page 50, line 5 skipping to change at page 51, line 5
The fs_locations struct and attribute then contains an array of The fs_locations struct and attribute then contains an array of
locations. Since the name space of each server may be constructed locations. Since the name space of each server may be constructed
differently, the "fs_root" field is provided. The path represented differently, the "fs_root" field is provided. The path represented
by fs_root represents the location of the file system in the server's by fs_root represents the location of the file system in the server's
name space. Therefore, the fs_root path is only associated with the name space. Therefore, the fs_root path is only associated with the
server from which the fs_locations attribute was obtained. The server from which the fs_locations attribute was obtained. The
fs_root path is meant to aid the client in locating the file system fs_root path is meant to aid the client in locating the file system
at the various servers listed. at the various servers listed.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
As an example, there is a replicated file system located at two As an example, there is a replicated file system located at two
servers (servA and servB). At servA the file system is located at 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 "/x/y/z". path "/a/b/c". At servB the file system is located at path "/x/y/z".
In this example the client accesses the file system first at servA In this example the client accesses the file system first at servA
with a multi-component lookup path of "/a/b/c/d". Since the client with a multi-component lookup path of "/a/b/c/d". Since the client
used a multi-component lookup to obtain the filehandle at "/a/b/c/d", used a multi-component lookup to obtain the filehandle at "/a/b/c/d",
it is unaware that the file system's root is located in servA's name it is unaware that the file system's root is located in servA's name
space at "/a/b/c". When the client switches to servB, it will need space at "/a/b/c". When the client switches to servB, it will need
to determine that the directory it first referenced at servA is now to determine that the directory it first referenced at servA is now
skipping to change at page 51, line 5 skipping to change at page 52, line 5
of the fh_expire_type attribute, whether volatile filehandles will of the fh_expire_type attribute, whether volatile filehandles will
expire at the migration or replication event. If the bit expire at the migration or replication event. If the bit
FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client
must treat the volatile filehandle as if the server had returned the must treat the volatile filehandle as if the server had returned the
NFS4ERR_FHEXPIRED error. At the migration or replication event in NFS4ERR_FHEXPIRED error. At the migration or replication event in
the presence of the FH4_VOL_MIGRATION bit, the client will not the presence of the FH4_VOL_MIGRATION bit, the client will not
present the original or old volatile file handle to the new server. present the original or old volatile file handle to the new server.
The client will start its communication with the new server by The client will start its communication with the new server by
recovering its filehandles using the saved file names. recovering its filehandles using the saved file names.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
7. NFS Server Name Space 7. NFS Server Name Space
7.1. Server Exports 7.1. Server Exports
On a UNIX server the name space describes all the files reachable by On a UNIX server the name space describes all the files reachable by
pathnames under the root directory or "/". On a Windows NT server pathnames under the root directory or "/". On a Windows NT server
the name space constitutes all the files on disks named by mapped the name space constitutes all the files on disks named by mapped
disk letters. NFS server administrators rarely make the entire disk letters. NFS server administrators rarely make the entire
server's file system name space available to NFS clients. More often server's file system name space available to NFS clients. More often
skipping to change at page 52, line 5 skipping to change at page 53, line 5
server's name space on the client: it is static. If the server server's name space on the client: it is static. If the server
administrator adds a new export the client will be unaware of it. administrator adds a new export the client will be unaware of it.
7.3. Server Pseudo File System 7.3. Server Pseudo File System
NFS version 4 servers avoid this name space inconsistency by NFS version 4 servers avoid this name space inconsistency by
presenting all the exports within the framework of a single server presenting all the exports within the framework of a single server
name space. An NFS version 4 client uses LOOKUP and READDIR name space. An NFS version 4 client uses LOOKUP and READDIR
operations to browse seamlessly from one export to another. Portions operations to browse seamlessly from one export to another. Portions
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
of the server name space that are not exported are bridged via a of the server name space that are not exported are bridged via a
"pseudo file system" that provides a view of exported directories "pseudo file system" that provides a view of exported directories
only. A pseudo file system has a unique fsid and behaves like a only. A pseudo file system has a unique fsid and behaves like a
normal, read only file system. normal, read only file system.
Based on the construction of the server's name space, it is possible Based on the construction of the server's name space, it is possible
that multiple pseudo file systems may exist. For example, that multiple pseudo file systems may exist. For example,
/a pseudo file system /a pseudo file system
skipping to change at page 53, line 5 skipping to change at page 54, line 5
7.6. Exported Root 7.6. Exported Root
If the server's root file system is exported, one might conclude that If the server's root file system is exported, one might conclude that
a pseudo-file system is not needed. This would be wrong. Assume the a pseudo-file system is not needed. This would be wrong. Assume the
following file systems on a server: following file systems on a server:
/ disk1 (exported) / disk1 (exported)
/a disk2 (not exported) /a disk2 (not exported)
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
/a/b disk3 (exported) /a/b disk3 (exported)
Because disk2 is not exported, disk3 cannot be reached with simple Because disk2 is not exported, disk3 cannot be reached with simple
LOOKUPs. The server must bridge the gap with a pseudo-file system. LOOKUPs. The server must bridge the gap with a pseudo-file system.
7.7. Mount Point Crossing 7.7. Mount Point Crossing
The server file system environment may be constructed in such a way The server file system environment may be constructed in such a way
that one file system contains a directory which is 'covered' or that one file system contains a directory which is 'covered' or
skipping to change at page 54, line 5 skipping to change at page 55, line 5
viewability of portions of the pseudo file system based on the viewability of portions of the pseudo file system based on the
server's perception of the client's ability to authenticate itself server's perception of the client's ability to authenticate itself
properly. However, with the support of multiple security mechanisms properly. However, with the support of multiple security mechanisms
and the ability to negotiate the appropriate use of these mechanisms, and the ability to negotiate the appropriate use of these mechanisms,
the server is unable to properly determine if a client will be able the server is unable to properly determine if a client will be able
to authenticate itself. If, based on its policies, the server to authenticate itself. If, based on its policies, the server
chooses to limit the contents of the pseudo file system, the server chooses to limit the contents of the pseudo file system, the server
may effectively hide file systems from a client that may otherwise may effectively hide file systems from a client that may otherwise
have legitimate access. have legitimate access.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
8. File Locking and Share Reservations 8. File Locking and Share Reservations
Integrating locking into the NFS protocol necessarily causes it to be Integrating locking into the NFS protocol necessarily causes it to be
state-full. With the inclusion of "share" file locks the protocol state-full. With the inclusion of "share" file locks the protocol
becomes substantially more dependent on state than the traditional becomes substantially more dependent on state than the traditional
combination of NFS and NLM [XNFS]. There are three components to combination of NFS and NLM [XNFS]. There are three components to
making this state manageable: making this state manageable:
o Clear division between client and server o Clear division between client and server
skipping to change at page 54, line 33 skipping to change at page 55, line 33
communicates its view of this state to the server as needed. The communicates its view of this state to the server as needed. The
client is also able to detect inconsistent state before modifying a client is also able to detect inconsistent state before modifying a
file. file.
To support Win32 "share" locks it is necessary to atomically OPEN or To support Win32 "share" locks it is necessary to atomically OPEN or
CREATE files. Having a separate share/unshare operation would not CREATE files. Having a separate share/unshare operation would not
allow correct implementation of the Win32 OpenFile API. In order to allow correct implementation of the Win32 OpenFile API. In order to
correctly implement share semantics, the previous NFS protocol correctly implement share semantics, the previous NFS protocol
mechanisms used when a file is opened or created (LOOKUP, CREATE, mechanisms used when a file is opened or created (LOOKUP, CREATE,
ACCESS) need to be replaced. The NFS version 4 protocol has an OPEN ACCESS) need to be replaced. The NFS version 4 protocol has an OPEN
operation that subsumes the functionality of LOOKUP, CREATE, and operation that subsumes the NFS version 3 methodology of LOOKUP,
ACCESS. However, because many operations require a filehandle, the CREATE, and ACCESS. However, because many operations require a
traditional LOOKUP is preserved to map a file name to filehandle filehandle, the traditional LOOKUP is preserved to map a file name to
without establishing state on the server. The policy of granting filehandle without establishing state on the server. The policy of
access or modifying files is managed by the server based on the granting access or modifying files is managed by the server based on
client's state. These mechanisms can implement policy ranging from the client's state. These mechanisms can implement policy ranging
advisory only locking to full mandatory locking. from advisory only locking to full mandatory locking.
8.1. Locking 8.1. Locking
It is assumed that manipulating a lock is rare when compared to READ It is assumed that manipulating a lock is rare when compared to READ
and WRITE operations. It is also assumed that crashes and network and WRITE operations. It is also assumed that crashes and network
partitions are relatively rare. Therefore it is important that the partitions are relatively rare. Therefore it is important that the
READ and WRITE operations have a lightweight mechanism to indicate if READ and WRITE operations have a lightweight mechanism to indicate if
they possess a held lock. A lock request contains the heavyweight they possess a held lock. A lock request contains the heavyweight
information required to establish a lock and uniquely define the lock information required to establish a lock and uniquely define the lock
owner. owner.
The following sections describe the transition from the heavy weight The following sections describe the transition from the heavy weight
information to the eventual stateid used for most client and server information to the eventual stateid used for most client and server
locking and lease interactions. locking and lease interactions.
8.1.1. Client ID 8.1.1. Client ID
For each LOCK request, the client must identify itself to the server. For each LOCK request, the client must identify itself to the server.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
This is done in such a way as to allow for correct lock This is done in such a way as to allow for correct lock
identification and crash recovery. Client identification is identification and crash recovery. Client identification is
accomplished with two values. accomplished with two values.
o A verifier that is used to detect client reboots. o A verifier that is used to detect client reboots.
o A variable length opaque array to uniquely define a client. o A variable length opaque array to uniquely define a client.
For an operating system this may be a fully qualified host For an operating system this may be a fully qualified host
skipping to change at page 55, line 57 skipping to change at page 56, line 57
a switched union that returns, in addition to a switched union that returns, in addition to
NFS4ERR_CLID_INUSE, the network address (the rpcbind netid NFS4ERR_CLID_INUSE, the network address (the rpcbind netid
and universal address) of the client that is using the id. and universal address) of the client that is using the id.
2 Client is re-connecting to the server after a client reboot 2 Client is re-connecting to the server after a client reboot
In this case, the client still generates an nfs_client_id In this case, the client still generates an nfs_client_id
but the nfs_client_id.id field will be the same as the but the nfs_client_id.id field will be the same as the
nfs_client_id.id generated prior to reboot. If the server nfs_client_id.id generated prior to reboot. If the server
finds that the principal/uid is equal to the previously finds that the principal/uid is equal to the previously
"registered" nfs_client_id.id, then locks associated with "registered" nfs_client_id.id, the server creates and
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
the old nfs_client_id are immediately released. If the returns a new clientid in response to the SETCLIENTID. If
principal/uid is not equal, then this is a rogue client and the principal/uid is not equal, then this is a rogue client
the request is returned in error. For more discussion of and the request is returned in error. For more discussion
crash recovery semantics, see the section on "Crash of crash recovery semantics, see the section on "Crash
Recovery". Recovery".
It is possible for a retransmission of request to be It is possible for a retransmission of request to be received by the
received by the server after the server has acted upon and server after the server has acted upon and responded to the original
responded to the original client request. Therefore to client request. Therefore to mitigate effects of the retransmission
mitigate effects of the retransmission of the SETCLIENTID of the SETCLIENTID operation, the client and server use a
operation, the client and server use a confirmation step. confirmation step. The client uses the SETCLIENTID_CONFIRM operation
The server returns a confirmation verifier that the client with the server provided clientid to confirm the client's use of the
then sends to the server in the SETCLIENTID_CONFIRM new clientid. Once the server receives the confirmation from the
operation. Once the server receives the confirmation from client, the locking state for the client is released.
the client, the locking state for the client is released.
In both cases, upon success, NFS4_OK is returned. To help reduce the In both cases, upon success, NFS4_OK is returned. To help reduce the
amount of data transferred on OPEN and LOCK, the server will also amount of data transferred on OPEN and LOCK, the server will also
return a unique 64-bit clientid value that is a shorthand reference return a unique 64-bit clientid value that is a shorthand reference
to the nfs_client_id values presented by the client. From this point to the nfs_client_id values presented by the client. From this point
forward, the client will use the clientid to refer to itself. forward, the client will use the clientid to refer to itself.
The clientid assigned by the server should be chosen so that it will The clientid assigned by the server should be chosen so that it will
not conflict with a clientid previously assigned by the server. This not conflict with a clientid previously assigned by the server. This
applies across server restarts or reboots. When a clientid is applies across server restarts or reboots. When a clientid is
skipping to change at page 57, line 4 skipping to change at page 57, line 57
for its clientid, the server may choose to release the clientid. The for its clientid, the server may choose to release the clientid. The
server may make this choice for an inactive client so that resources server may make this choice for an inactive client so that resources
are not consumed by those intermittently active clients. If the are not consumed by those intermittently active clients. If the
client contacts the server after this release, the server must ensure client contacts the server after this release, the server must ensure
the client receives the appropriate error so that it will use the the client receives the appropriate error so that it will use the
SETCLIENTID/SETCLIENTID_CONFIRM sequence to establish a new identity. SETCLIENTID/SETCLIENTID_CONFIRM sequence to establish a new identity.
It should be clear that the server must be very hesitant to release a It should be clear that the server must be very hesitant to release a
clientid since the resulting work on the client to recover from such clientid since the resulting work on the client to recover from such
an event will be the same burden as if the server had failed and an event will be the same burden as if the server had failed and
restarted. Typically a server would not release a clientid unless restarted. Typically a server would not release a clientid unless
Draft Specification NFS version 4 Protocol November 2001
there had been no activity from that client for many minutes. there had been no activity from that client for many minutes.
Draft Specification NFS version 4 Protocol July 2002
8.1.3. nfs_lockowner and stateid Definition 8.1.3. nfs_lockowner and stateid Definition
When requesting a lock, the client must present to the server the When requesting a lock, the client must present to the server the
clientid and an identifier for the owner of the requested lock. clientid and an identifier for the owner of the requested lock.
These two fields are referred to as the nfs_lockowner and the These two fields are referred to as the nfs_lockowner and the
definition of those fields are: definition of those fields are:
o A clientid returned by the server as part of the client's use of o A clientid returned by the server as part of the client's use of
the SETCLIENTID operation. the SETCLIENTID operation.
skipping to change at page 58, line 4 skipping to change at page 58, line 55
operations has occurred). The error NFS4ERR_OLD_STATEID should operations has occurred). The error NFS4ERR_OLD_STATEID should
be returned. be returned.
This error condition will only occur when the client issues a This error condition will only occur when the client issues a
locking request which changes a stateid while an I/O request locking request which changes a stateid while an I/O request
that uses that stateid is outstanding. that uses that stateid is outstanding.
o The stateid was generated by the current server instance but the o The stateid was generated by the current server instance but the
stateid does not designate a locking state for any active stateid does not designate a locking state for any active
lockowner-file pair. The error NFS4ERR_BAD_STATEID should be lockowner-file pair. The error NFS4ERR_BAD_STATEID should be
Draft Specification NFS version 4 Protocol November 2001
returned. returned.
This error condition will occur when there has been a logic This error condition will occur when there has been a logic
Draft Specification NFS version 4 Protocol July 2002
error on the part of the client or server. This should not error on the part of the client or server. This should not
happen. happen.
One mechanism that may be used to satisfy these requirements is for One mechanism that may be used to satisfy these requirements is for
the server to divide stateids into three fields: the server to divide stateids into three fields:
o A server verifier which uniquely designates a particular server o A server verifier which uniquely designates a particular server
instantiation. instantiation.
o An index into a table of locking-state structures. o An index into a table of locking-state structures.
skipping to change at page 58, line 32 skipping to change at page 59, line 29
associated with the same index into the locking-state table. associated with the same index into the locking-state table.
By matching the incoming stateid and its field values with the state By matching the incoming stateid and its field values with the state
held at the server, the server is able to easily determine if a held at the server, the server is able to easily determine if a
stateid is valid for its current instantiation and state. If the stateid is valid for its current instantiation and state. If the
stateid is not valid, the appropriate error can be supplied to the stateid is not valid, the appropriate error can be supplied to the
client. client.
8.1.4. Use of the stateid 8.1.4. Use of the stateid
All READ and WRITE operations contain a stateid. If the All READ, WRITE and SETATTR operations contain a stateid. For the
nfs_lockowner performs a READ or WRITE on a range of bytes within a purposes of this section, SETATTR operations which change the size
locked range, the stateid (previously returned by the server) must be attribute of a file are treated as if they are writing the area
used to indicate that the appropriate lock (record or share) is held. between the old and new size (i.e. the range truncated or added to
If no state is established by the client, either record lock or share the file by means of the SETATTR), even where SETATTR is not
lock, a stateid of all bits 0 is used. If no conflicting locks are explicitly mentioned in the text.
held on the file, the server may service the READ or WRITE operation.
If a conflict with an explicit lock occurs, an error is returned for
the operation (NFS4ERR_LOCKED). This allows "mandatory locking" to be
implemented.
A stateid of all bits 1 (one) allows READ operations to bypass record If the nfs_lockowner performs a READ or WRITE in a situation in which
locking checks at the server. However, WRITE operations with stateid it has established a lock on the server (and for these purposes any
with bits all 1 (one) do not bypass record locking checks. File OPEN constitutes a share lock) the stateid (previously returned by
locking checks are handled by the OPEN operation (see the section the server) must be used to indicate what locks, including both
"OPEN/CLOSE Operations"). record and share locks, are held by the lockowner. If no state is
established by the client, either record lock or share lock, a
stateid of all bits 0 is used. Regardless of whether a stateid of
all bits 0, or a stateid returned by the server is used, if no
conflicting locks are held on the file, the server may service the
READ or WRITE operation. If a conflict with an explicit lock occurs,
an error is returned for the operation (NFS4ERR_LOCKED). This allows
"mandatory locking" to be implemented.
Share locks are established by OPEN operations and by their nature
are mandatory in that when the OPEN denies READ or WRITE operations,
that denial results in such operations being rejected with error
NFS4ERR_LOCKED. Record locks may be implemented by the server as
either mandatory or advisory, or the choice of mandatory or advisory
behavior may be determined by the server on the basis of the file
being accessed. When record locks are advisory, they only prevent
the granting of conflicting lock requests and have no effect on
Draft Specification NFS version 4 Protocol July 2002
READ's or WRITE's. Mandatory record locks, however, prevent
conflicting IO operations and when they are attempted, they are
rejected with NFS4ERR_LOCKED.
Every stateid other than the special stateid values noted above,
whether returned by an OPEN-type operation (i.e. OPEN,
OPEN_DOWNGRADE), or by a LOCK-type operation (i.e. LOCK or LOCKU),
defines an access mode for the file (i.e. READ, WRITE, or READ_WRITE)
as established by the original OPEN which began the stateid sequence,
and as modified by subsequent OPEN's and OPEN_DOWNGRADE's within that
stateid sequence. When a READ, WRITE, or SETATTR which specifies the
size attribute, is done, the operation is subject to checking against
the access mode to verify that the operation is appropriate given the
OPEN with which the operation is associated.
In the case of WRITE-type operations (i.e. WRITE's and SETATTR's
which set size), the server must verify that the access mode allows
writing and return an NFS4ERR_OPENMODE error if it does not. In the
case, of READ, the server may perform the corresponding check on the
access mode, or it may choose to allow READ on opens for WRITE only,
to accommodate clients whose write implementation may unavoidably do
reads (e.g. due to buffer cache constraints). However, even if
READ's are allowed in these circumstances, the server MUST still
check for locks that conflict with the READ (e.g. another open
specify denial of READ's). Note that a server which does enforce the
access mode check on READ's need not explicitly check for conflicting
share reservations since the existence of OPEN for read access
guarantees that no conflicting share reservation can exist.
A stateid of all bits 1 (one) allows READ operations to bypass
locking checks at the server. However, WRITE operations with a
stateid with bits all 1 (one) do not bypass locking checks and are
treated exactly the same as if a stateid of all bits 0 were used.
An explicit lock may not be granted while a READ or WRITE operation An explicit lock may not be granted while a READ or WRITE operation
with conflicting implicit locking is being performed. with conflicting implicit locking is being performed. For the
purposes of this paragraph, a READ is considered as having an
implicit shared record lock for the area being read while a WRITE is
considered as having an implicit exclusive record lock for the area
being written (and similarly for SETATTR's that set size as discussed
above).
8.1.5. Sequencing of Lock Requests 8.1.5. Sequencing of Lock Requests
Locking is different than most NFS operations as it requires "at- Locking is different than most NFS operations as it requires "at-
most-one" semantics that are not provided by ONCRPC. ONCRPC over a most-one" semantics that are not provided by ONCRPC. ONCRPC over a
Draft Specification NFS version 4 Protocol November 2001
reliable transport is not sufficient because a sequence of locking reliable transport is not sufficient because a sequence of locking
requests may span multiple TCP connections. In the face of requests may span multiple TCP connections. In the face of
retransmission or reordering, lock or unlock requests must have a retransmission or reordering, lock or unlock requests must have a
well defined and consistent behavior. To accomplish this, each lock well defined and consistent behavior. To accomplish this, each lock
request contains a sequence number that is a consecutively increasing request contains a sequence number that is a consecutively increasing
Draft Specification NFS version 4 Protocol July 2002
integer. Different nfs_lockowners have different sequences. The integer. Different nfs_lockowners have different sequences. The
server maintains the last sequence number (L) received and the server maintains the last sequence number (L) received and the
response that was returned. response that was returned.
Note that for requests that contain a sequence number, for each Note that for requests that contain a sequence number, for each
nfs_lockowner, there should be no more than one outstanding request. nfs_lockowner, there should be no more than one outstanding request.
If a request with a previous sequence number (r < L) is received, it If a request (r) with a previous sequence number (r < L) is received,
is rejected with the return of error NFS4ERR_BAD_SEQID. Given a it is rejected with the return of error NFS4ERR_BAD_SEQID. Given a
properly-functioning client, the response to (r) must have been properly-functioning client, the response to (r) must have been
received before the last request (L) was sent. If a duplicate of received before the last request (L) was sent. If a duplicate of
last request (r == L) is received, the stored response is returned. last request (r == L) is received, the stored response is returned.
If a request beyond the next sequence (r == L + 2) is received, it is If a request beyond the next sequence (r == L + 2) is received, it is
rejected with the return of error NFS4ERR_BAD_SEQID. Sequence rejected with the return of error NFS4ERR_BAD_SEQID. Sequence
history is reinitialized whenever the client verifier changes. history is reinitialized whenever the client verifier changes.
Since the sequence number is represented with an unsigned 32-bit Since the sequence number is represented with an unsigned 32-bit
integer, the arithmetic involved with the sequence number is mod integer, the arithmetic involved with the sequence number is mod
2^32. 2^32.
skipping to change at page 59, line 46 skipping to change at page 61, line 41
algorithm for removing unneeded requests. However, the last lock algorithm for removing unneeded requests. However, the last lock
request and response on a given nfs_lockowner must be cached as long request and response on a given nfs_lockowner must be cached as long
as the lock state exists on the server. as the lock state exists on the server.
8.1.6. Recovery from Replayed Requests 8.1.6. Recovery from Replayed Requests
As described above, the sequence number is per nfs_lockowner. As As described above, the sequence number is per nfs_lockowner. As
long as the server maintains the last sequence number received and long as the server maintains the last sequence number received and
follows the methods described above, there are no risks of a follows the methods described above, there are no risks of a
Byzantine router re-sending old requests. The server need only Byzantine router re-sending old requests. The server need only
maintain the nfs_lockowner, sequence number state as long as there maintain the (nfs_lockowner, sequence number) state as long as there
are open files or closed files with locks outstanding. are open files or closed files with locks outstanding.
LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence LOCK, LOCKU, OPEN, OPEN_DOWNGRADE, and CLOSE each contain a sequence
number and therefore the risk of the replay of these operations number and therefore the risk of the replay of these operations
resulting in undesired effects is non-existent while the server resulting in undesired effects is non-existent while the server
maintains the nfs_lockowner state. maintains the nfs_lockowner state.
8.1.7. Releasing nfs_lockowner State 8.1.7. Releasing nfs_lockowner State
When a particular nfs_lockowner no longer holds open or file locking When a particular nfs_lockowner no longer holds open or file locking
Draft Specification NFS version 4 Protocol November 2001
state at the server, the server may choose to release the sequence state at the server, the server may choose to release the sequence
number state associated with the nfs_lockowner. The server may make number state associated with the nfs_lockowner. The server may make
this choice based on lease expiration, for the reclamation of server this choice based on lease expiration, for the reclamation of server
memory, or other implementation specific details. In any event, the memory, or other implementation specific details. In any event, the
server is able to do this safely only when the nfs_lockowner no server is able to do this safely only when the nfs_lockowner no
Draft Specification NFS version 4 Protocol July 2002
longer is being utilized by the client. The server may choose to longer is being utilized by the client. The server may choose to
hold the nfs_lockowner state in the event that retransmitted requests hold the nfs_lockowner state in the event that retransmitted requests
are received. However, the period to hold this state is are received. However, the period to hold this state is
implementation specific. implementation specific.
In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is In the case that a LOCK, LOCKU, OPEN_DOWNGRADE, or CLOSE is
retransmitted after the server has previously released the retransmitted after the server has previously released the
nfs_lockowner state, the server will find that the nfs_lockowner has nfs_lockowner state, the server will find that the nfs_lockowner has
no files open and an error will be returned to the client. If the no files open and an error will be returned to the client. If the
nfs_lockowner does have a file open, the stateid will not match and nfs_lockowner does have a file open, the stateid will not match and
skipping to change at page 60, line 36 skipping to change at page 62, line 31
previously released by the server, the use of the OPEN_CONFIRM previously released by the server, the use of the OPEN_CONFIRM
operation will prevent incorrect behavior. When the server observes operation will prevent incorrect behavior. When the server observes
the use of the nfs_lockowner for the first time, it will direct the the use of the nfs_lockowner for the first time, it will direct the
client to perform the OPEN_CONFIRM for the corresponding OPEN. This client to perform the OPEN_CONFIRM for the corresponding OPEN. This
sequence establishes the use of an nfs_lockowner and associated sequence establishes the use of an nfs_lockowner and associated
sequence number. See the section "OPEN_CONFIRM - Confirm Open" for sequence number. See the section "OPEN_CONFIRM - Confirm Open" for
further details. further details.
8.2. Lock Ranges 8.2. Lock Ranges
The protocol allows a lock owner to request a lock with one byte The protocol allows a lock owner to request a lock with a byte range
range and then either upgrade or unlock a sub-range of the initial and then either upgrade or unlock a sub-range of the initial lock.
lock. It is expected that this will be an uncommon type of request. It is expected that this will be an uncommon type of request. In any
In any case, servers or server file systems may not be able to case, servers or server file systems may not be able to support sub-
support sub-range lock semantics. In the event that a server range lock semantics. In the event that a server receives a locking
receives a locking request that represents a sub-range of current request that represents a sub-range of current locking state for the
locking state for the lock owner, the server is allowed to return the lock owner, the server is allowed to return the error
error NFS4ERR_LOCK_RANGE to signify that it does not support sub- NFS4ERR_LOCK_RANGE to signify that it does not support sub-range lock
range lock operations. Therefore, the client should be prepared to operations. Therefore, the client should be prepared to receive this
receive this error and, if appropriate, report the error to the error and, if appropriate, report the error to the requesting
requesting application. application.
The client is discouraged from combining multiple independent locking The client is discouraged from combining multiple independent locking
ranges that happen to be adjacent into a single request since the ranges that happen to be adjacent into a single request since the
server may not support sub-range requests and for reasons related to server may not support sub-range requests and for reasons related to
the recovery of file locking state in the event of server failure. the recovery of file locking state in the event of server failure.
As discussed in the section "Server Failure and Recovery" below, the As discussed in the section "Server Failure and Recovery" below, the
server may employ certain optimizations during recovery that work server may employ certain optimizations during recovery that work
effectively only when the client's behavior during lock recovery is effectively only when the client's behavior during lock recovery is
similar to the client's locking behavior prior to server failure. similar to the client's locking behavior prior to server failure.
Draft Specification NFS version 4 Protocol November 2001
8.3. Blocking Locks 8.3. Blocking Locks
Some clients require the support of blocking locks. The NFS version Some clients require the support of blocking locks. The NFS version
4 protocol must not rely on a callback mechanism and therefore is 4 protocol must not rely on a callback mechanism and therefore is
unable to notify a client when a previously denied lock has been unable to notify a client when a previously denied lock has been
Draft Specification NFS version 4 Protocol July 2002
granted. Clients have no choice but to continually poll for the granted. Clients have no choice but to continually poll for the
lock. This presents a fairness problem. Two new lock types are lock. This presents a fairness problem. Two new lock types are
added, READW and WRITEW, and are used to indicate to the server that added, READW and WRITEW, and are used to indicate to the server that
the client is requesting a blocking lock. The server should maintain the client is requesting a blocking lock. The server should maintain
an ordered list of pending blocking locks. When the conflicting lock an ordered list of pending blocking locks. When the conflicting lock
is released, the server may wait the lease period for the first is released, the server may wait the lease period for the first
waiting client to re-request the lock. After the lease period waiting client to re-request the lock. After the lease period
expires the next waiting client request is allowed the lock. Clients expires the next waiting client request is allowed the lock. Clients
are required to poll at an interval sufficiently small that it is are required to poll at an interval sufficiently small that it is
likely to acquire the lock in a timely manner. The server is not likely to acquire the lock in a timely manner. The server is not
skipping to change at page 61, line 50 skipping to change at page 63, line 45
renewals may not be denied if the lease interval has not expired. renewals may not be denied if the lease interval has not expired.
The following events cause implicit renewal of all of the leases for The following events cause implicit renewal of all of the leases for
a given client (i.e. all those sharing a given clientid). Each of a given client (i.e. all those sharing a given clientid). Each of
these is a positive indication that the client is still active and these is a positive indication that the client is still active and
that the associated state held at the server, for the client, is that the associated state held at the server, for the client, is
still valid. still valid.
o An OPEN with a valid clientid. o An OPEN with a valid clientid.
o Any operation made with a valid stateid (CLOSE, DELEGRETURN, o Any operation made with a valid stateid (CLOSE, DELEGPURGE,
LOCK, LOCKU, OPEN, OPEN_CONFIRM, READ, RENEW, SETATTR, WRITE). DELEGRETURN, LOCK, LOCKU, OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE,
This does not include the special stateids of all bits 0 or all READ, RENEW, SETATTR, SETCLIENTID_CONFIRM, WRITE). This does
bits 1. not include the special stateids of all bits 0 or all bits 1.
Note that if the client had restarted or rebooted, the Note that if the client had restarted or rebooted, the
client would not be making these requests without issuing client would not be making these requests without issuing
the SETCLIENTID operation. The use of the SETCLIENTID the SETCLIENTID/SETCLIENTID_CONFIRM sequence. The use of
the SETCLIENTID/SETCLIENTID_CONFIRM operations notifies the
server to drop the locking state associated with the
client.
Draft Specification NFS version 4 Protocol November 2001 If the server has rebooted, the stateids
operation (possibly with the addition of the optional Draft Specification NFS version 4 Protocol July 2002
SETCLIENTID_CONFIRM operation) notifies the server to drop
the locking state associated with the client.
If the server has rebooted, the stateids
(NFS4ERR_STALE_STATEID error) or the clientid (NFS4ERR_STALE_STATEID error) or the clientid
(NFS4ERR_STALE_CLIENTID error) will not be valid hence (NFS4ERR_STALE_CLIENTID error) will not be valid hence
preventing spurious renewals. preventing spurious renewals.
This approach allows for low overhead lease renewal which scales This approach allows for low overhead lease renewal which scales
well. In the typical case no extra RPC calls are required for lease well. In the typical case no extra RPC calls are required for lease
renewal and in the worst case one RPC is required every lease period renewal and in the worst case one RPC is required every lease period
(i.e. a RENEW operation). The number of locks held by the client is (i.e. a RENEW operation). The number of locks held by the client is
not a factor since all state for the client is involved with the not a factor since all state for the client is involved with the
lease renewal action. lease renewal action.
skipping to change at page 62, line 51 skipping to change at page 64, line 46
locks when the associated leases have expired. Conflicting locks locks when the associated leases have expired. Conflicting locks
from another client may only be granted after this lease expiration. from another client may only be granted after this lease expiration.
If the client is able to restart or reinitialize within the lease If the client is able to restart or reinitialize within the lease
period the client may be forced to wait the remainder of the lease period the client may be forced to wait the remainder of the lease
period before obtaining new locks. period before obtaining new locks.
To minimize client delay upon restart, lock requests are associated To minimize client delay upon restart, lock requests are associated
with an instance of the client by a client supplied verifier. This with an instance of the client by a client supplied verifier. This
verifier is part of the initial SETCLIENTID call made by the client. verifier is part of the initial SETCLIENTID call made by the client.
The server returns a clientid as a result of the SETCLIENTID The server returns a clientid as a result of the SETCLIENTID
operation. The client then confirms the use of the verifier with operation. The client then confirms the use of the clientid with
SETCLIENTID_CONFIRM. The clientid in combination with an opaque SETCLIENTID_CONFIRM. The clientid in combination with an opaque
owner field is then used by the client to identify the lock owner for owner field is then used by the client to identify the lock owner for
OPEN. This chain of associations is then used to identify all locks OPEN. This chain of associations is then used to identify all locks
for a particular client. for a particular client.
Draft Specification NFS version 4 Protocol November 2001
Since the verifier will be changed by the client upon each Since the verifier will be changed by the client upon each
initialization, the server can compare a new verifier to the verifier initialization, the server can compare a new verifier to the verifier
associated with currently held locks and determine that they do not associated with currently held locks and determine that they do not
match. This signifies the client's new instantiation and subsequent match. This signifies the client's new instantiation and subsequent
loss of locking state. As a result, the server is free to release loss of locking state. As a result, the server is free to release
Draft Specification NFS version 4 Protocol July 2002
all locks held which are associated with the old clientid which was all locks held which are associated with the old clientid which was
derived from the old verifier. derived from the old verifier.
For secure environments, a change in the verifier must only cause the For secure environments, a change in the verifier must only cause the
release of locks associated with the authenticated requester. This release of locks associated with the authenticated requester. This
is required to prevent a rogue entity from freeing otherwise valid is required to prevent a rogue entity from freeing otherwise valid
locks. locks.
Note that the verifier must have the same uniqueness properties of Note that the verifier must have the same uniqueness properties of
the verifier for the COMMIT operation. the verifier for the COMMIT operation.
skipping to change at page 64, line 4 skipping to change at page 65, line 53
CLAIM_PREVIOUS). During the grace period, the server must reject CLAIM_PREVIOUS). During the grace period, the server must reject
READ and WRITE operations and non-reclaim locking requests (i.e. READ and WRITE operations and non-reclaim locking requests (i.e.
other LOCK and OPEN operations) with an error of NFS4ERR_GRACE. other LOCK and OPEN operations) with an error of NFS4ERR_GRACE.
If the server can reliably determine that granting a non-reclaim If the server can reliably determine that granting a non-reclaim
request will not conflict with reclamation of locks by other clients, request will not conflict with reclamation of locks by other clients,
the NFS4ERR_GRACE error does not have to be returned and the non- the NFS4ERR_GRACE error does not have to be returned and the non-
reclaim client request can be serviced. For the server to be able to reclaim client request can be serviced. For the server to be able to
service READ and WRITE operations during the grace period, it must service READ and WRITE operations during the grace period, it must
again be able to guarantee that no possible conflict could arise again be able to guarantee that no possible conflict could arise
Draft Specification NFS version 4 Protocol November 2001
between an impending reclaim locking request and the READ or WRITE between an impending reclaim locking request and the READ or WRITE
operation. If the server is unable to offer that guarantee, the operation. If the server is unable to offer that guarantee, the
NFS4ERR_GRACE error must be returned to the client. NFS4ERR_GRACE error must be returned to the client.
For a server to provide simple, valid handling during the grace For a server to provide simple, valid handling during the grace
Draft Specification NFS version 4 Protocol July 2002
period, the easiest method is to simply reject all non-reclaim period, the easiest method is to simply reject all non-reclaim
locking requests and READ and WRITE operations by returning the locking requests and READ and WRITE operations by returning the
NFS4ERR_GRACE error. However, a server may keep information about NFS4ERR_GRACE error. However, a server may keep information about
granted locks in stable storage. With this information, the server granted locks in stable storage. With this information, the server
could determine if a regular lock or READ or WRITE operation can be could determine if a regular lock or READ or WRITE operation can be
safely processed. safely processed.
For example, if a count of locks on a given file is available in For example, if a count of locks on a given file is available in
stable storage, the server can track reclaimed locks for the file and stable storage, the server can track reclaimed locks for the file and
when all reclaims have been processed, non-reclaim locking requests when all reclaims have been processed, non-reclaim locking requests
skipping to change at page 65, line 4 skipping to change at page 66, line 53
8.5.3. Network Partitions and Recovery 8.5.3. Network Partitions and Recovery
If the duration of a network partition is greater than the lease If the duration of a network partition is greater than the lease
period provided by the server, the server will have not received a period provided by the server, the server will have not received a
lease renewal from the client. If this occurs, the server may free lease renewal from the client. If this occurs, the server may free
all locks held for the client. As a result, all stateids held by the all locks held for the client. As a result, all stateids held by the
client will become invalid or stale. Once the client is able to client will become invalid or stale. Once the client is able to
reach the server after such a network partition, all I/O submitted by reach the server after such a network partition, all I/O submitted by
the client with the now invalid stateids will fail with the server the client with the now invalid stateids will fail with the server
returning the error NFS4ERR_EXPIRED. Once this error is received, returning the error NFS4ERR_EXPIRED. Once this error is received,
Draft Specification NFS version 4 Protocol November 2001
the client will suitably notify the application that held the lock. the client will suitably notify the application that held the lock.
As a courtesy to the client or as an optimization, the server may As a courtesy to the client or as an optimization, the server may
continue to hold locks on behalf of a client for which recent continue to hold locks on behalf of a client for which recent
communication has extended beyond the lease period. If the server communication has extended beyond the lease period. If the server
Draft Specification NFS version 4 Protocol July 2002
receives a lock or I/O request that conflicts with one of these receives a lock or I/O request that conflicts with one of these
courtesy locks, the server must free the courtesy lock and grant the courtesy locks, the server must free the courtesy lock and grant the
new request. new request.
If the server continues to hold locks beyond the expiration of a If the server continues to hold locks beyond the expiration of a
client's lease, the server MUST employ a method of recording this client's lease, the server MUST employ a method of recording this
fact in its stable storage. Conflicting locks requests from another fact in its stable storage. Conflicting locks requests from another
client may be serviced after the lease expiration. There are various client may be serviced after the lease expiration. There are various
scenarios involving server failure after such an event that require scenarios involving server failure after such an event that require
the storage of these lease expirations or network partitions. One the storage of these lease expirations or network partitions. One
skipping to change at page 65, line 53 skipping to change at page 67, line 48
conflicting lock. The choice of the amount and type of state conflicting lock. The choice of the amount and type of state
information that is stored is left to the implementor. In any case, information that is stored is left to the implementor. In any case,
the server must have enough state information to enable correct the server must have enough state information to enable correct
recovery from multiple partitions and multiple server failures. recovery from multiple partitions and multiple server failures.
8.6. Recovery from a Lock Request Timeout or Abort 8.6. Recovery from a Lock Request Timeout or Abort
In the event a lock request times out, a client may decide to not In the event a lock request times out, a client may decide to not
retry the request. The client may also abort the request when the retry the request. The client may also abort the request when the
process for which it was issued is terminated (e.g. in UNIX due to a process for which it was issued is terminated (e.g. in UNIX due to a
signal. It is possible though that the server received the request signal). It is possible though that the server received the request
and acted upon it. This would change the state on the server without and acted upon it. This would change the state on the server without
the client being aware of the change. It is paramount that the the client being aware of the change. It is paramount that the
client re-synchronize state with server before it attempts any other client re-synchronize state with server before it attempts any other
Draft Specification NFS version 4 Protocol November 2001
operation that takes a seqid and/or a stateid with the same operation that takes a seqid and/or a stateid with the same
nfs_lockowner. This is straightforward to do without a special re- nfs_lockowner. This is straightforward to do without a special re-
synchronize operation. synchronize operation.
Since the server maintains the last lock request and response Since the server maintains the last lock request and response
Draft Specification NFS version 4 Protocol July 2002
received on the nfs_lockowner, for each nfs_lockowner, the client received on the nfs_lockowner, for each nfs_lockowner, the client
should cache the last lock request it sent such that the lock request should cache the last lock request it sent such that the lock request
did not receive a response. From this, the next time the client does did not receive a response. From this, the next time the client does
a lock operation for the nfs_lockowner, it can send the cached a lock operation for the nfs_lockowner, it can send the cached
request, if there is one, and if the request was one that established request, if there is one, and if the request was one that established
state (e.g. a LOCK or OPEN operation) the client can follow up with a state (e.g. a LOCK or OPEN operation) the client can follow up with a
request to remove the state (e.g. a LOCKU or CLOSE operation). With request to remove the state (e.g. a LOCKU or CLOSE operation). With
this approach, the sequencing and stateid information on the client this approach, the sequencing and stateid information on the client
and server for the given nfs_lockowner will re-synchronize and in and server for the given nfs_lockowner will re-synchronize and in
turn the lock state will re-synchronize. turn the lock state will re-synchronize.
skipping to change at page 67, line 4 skipping to change at page 68, line 53
have occurred on the server and thus determine if it is possible that have occurred on the server and thus determine if it is possible that
a lease period expiration could have occurred. a lease period expiration could have occurred.
The third lock revocation event can occur as a result of The third lock revocation event can occur as a result of
administrative intervention within the lease period. While this is administrative intervention within the lease period. While this is
considered a rare event, it is possible that the server's considered a rare event, it is possible that the server's
administrator has decided to release or revoke a particular lock held administrator has decided to release or revoke a particular lock held
by the client. As a result of revocation, the client will receive an by the client. As a result of revocation, the client will receive an
error of NFS4ERR_EXPIRED and the error is received within the lease error of NFS4ERR_EXPIRED and the error is received within the lease
period for the lock. In this instance the client may assume that period for the lock. In this instance the client may assume that
Draft Specification NFS version 4 Protocol November 2001
only the nfs_lockowner's locks have been lost. The client notifies only the nfs_lockowner's locks have been lost. The client notifies
the lock holder appropriately. The client may not assume the lease the lock holder appropriately. The client may not assume the lease
period has been renewed as a result of failed operation. period has been renewed as a result of failed operation.
When the client determines the lease period may have expired, the When the client determines the lease period may have expired, the
Draft Specification NFS version 4 Protocol July 2002
client must mark all locks held for the associated lease as client must mark all locks held for the associated lease as
"unvalidated". This means the client has been unable to re-establish "unvalidated". This means the client has been unable to re-establish
or confirm the appropriate lock state with the server. As described or confirm the appropriate lock state with the server. As described
in the previous section on crash recovery, there are scenarios in in the previous section on crash recovery, there are scenarios in
which the server may grant conflicting locks after the lease period which the server may grant conflicting locks after the lease period
has expired for a client. When it is possible that the lease period has expired for a client. When it is possible that the lease period
has expired, the client must validate each lock currently held to has expired, the client must validate each lock currently held to
ensure that a conflicting lock has not been granted. The client may ensure that a conflicting lock has not been granted. The client may
accomplish this task by issuing an I/O request, either a pending I/O accomplish this task by issuing an I/O request, either a pending I/O
or a zero-length read, specifying the stateid associated with the or a zero-length read, specifying the stateid associated with the
skipping to change at page 68, line 5 skipping to change at page 69, line 51
const OPEN4_SHARE_ACCESS_READ = 0x00000001; const OPEN4_SHARE_ACCESS_READ = 0x00000001;
const OPEN4_SHARE_ACCESS_WRITE = 0x00000002; const OPEN4_SHARE_ACCESS_WRITE = 0x00000002;
const OPEN4_SHARE_ACCESS_BOTH = 0x00000003; const OPEN4_SHARE_ACCESS_BOTH = 0x00000003;
const OPEN4_SHARE_DENY_NONE = 0x00000000; const OPEN4_SHARE_DENY_NONE = 0x00000000;
const OPEN4_SHARE_DENY_READ = 0x00000001; const OPEN4_SHARE_DENY_READ = 0x00000001;
const OPEN4_SHARE_DENY_WRITE = 0x00000002; const OPEN4_SHARE_DENY_WRITE = 0x00000002;
const OPEN4_SHARE_DENY_BOTH = 0x00000003; const OPEN4_SHARE_DENY_BOTH = 0x00000003;
Draft Specification NFS version 4 Protocol November 2001
8.9. OPEN/CLOSE Operations 8.9. OPEN/CLOSE Operations
To provide correct share semantics, a client MUST use the OPEN To provide correct share semantics, a client MUST use the OPEN
operation to obtain the initial filehandle and indicate the desired operation to obtain the initial filehandle and indicate the desired
access and what if any access to deny. Even if the client intends to access and what if any access to deny. Even if the client intends to
Draft Specification NFS version 4 Protocol July 2002
use a stateid of all 0's or all 1's, it must still obtain the use a stateid of all 0's or all 1's, it must still obtain the
filehandle for the regular file with the OPEN operation so the filehandle for the regular file with the OPEN operation so the
appropriate share semantics can be applied. For clients that do not appropriate share semantics can be applied. For clients that do not
have a deny mode built into their open programming interfaces, deny have a deny mode built into their open programming interfaces, deny
equal to NONE should be used. equal to NONE should be used.
The OPEN operation with the CREATE flag, also subsumes the CREATE The OPEN operation with the CREATE flag, also subsumes the CREATE
operation for regular files as used in previous versions of the NFS operation for regular files as used in previous versions of the NFS
protocol. This allows a create with a share to be done atomically. protocol. This allows a create with a share to be done atomically.
skipping to change at page 69, line 4 skipping to change at page 70, line 53
in the OPEN'ed object being designated by the same filehandle. in the OPEN'ed object being designated by the same filehandle.
When the server chooses to export multiple filehandles corresponding When the server chooses to export multiple filehandles corresponding
to the same file object and returns different filehandles on two to the same file object and returns different filehandles on two
different OPEN's of the same file object, the server MUST NOT "OR" different OPEN's of the same file object, the server MUST NOT "OR"
together the access and deny bits and coalesce the two open files. together the access and deny bits and coalesce the two open files.
Instead the server must maintain separate OPEN's with separate Instead the server must maintain separate OPEN's with separate
stateid's and will require separate CLOSE's to free them. stateid's and will require separate CLOSE's to free them.
When multiple open files on the client are merged into a single open When multiple open files on the client are merged into a single open
Draft Specification NFS version 4 Protocol November 2001
file object on the server, the close of one of the open files (on the file object on the server, the close of one of the open files (on the
client) may necessitate change of the access and deny status of the client) may necessitate change of the access and deny status of the
open file on the server. This is because the union of the access and open file on the server. This is because the union of the access and
deny bits for the remaining open's may be smaller (i.e. a proper deny bits for the remaining open's may be smaller (i.e. a proper
subset) than previously. The OPEN_DOWNGRADE operation is used to subset) than previously. The OPEN_DOWNGRADE operation is used to
Draft Specification NFS version 4 Protocol July 2002
make the necessary change and the client should use it to update the make the necessary change and the client should use it to update the
server so that share reservation requests by other clients are server so that share reservation requests by other clients are
handled properly. handled properly.
8.11. Short and Long Leases 8.11. Short and Long Leases
When determining the time period for the server lease, the usual When determining the time period for the server lease, the usual
lease tradeoffs apply. Short leases are good for fast server lease tradeoffs apply. Short leases are good for fast server
recovery at a cost of increased RENEW or READ (with zero length) recovery at a cost of increased RENEW or READ (with zero length)
requests. Longer leases are certainly kinder and gentler to large requests. Longer leases are certainly kinder and gentler to large
skipping to change at page 70, line 5 skipping to change at page 71, line 48
retransmitted. retransmitted.
To take propagation delay into account, the client should subtract it To take propagation delay into account, the client should subtract it
from lease times (e.g. if the client estimates the one-way from lease times (e.g. if the client estimates the one-way
propagation delay as 200 msec, then it can assume that the lease is propagation delay as 200 msec, then it can assume that the lease is
already 200 msec old when it gets it). In addition, it will take already 200 msec old when it gets it). In addition, it will take
another 200 msec to get a response back to the server. So the client another 200 msec to get a response back to the server. So the client
must send a lock renewal or write data back to the server 400 msec must send a lock renewal or write data back to the server 400 msec
before the lease would expire. before the lease would expire.
Draft Specification NFS version 4 Protocol November 2001
8.13. Migration, Replication and State 8.13. Migration, Replication and State
When responsibility for handling a given file system is transferred When responsibility for handling a given file system is transferred
to a new server (migration) or the client chooses to use an alternate to a new server (migration) or the client chooses to use an alternate
server (e.g. in response to server unresponsiveness) in the context server (e.g. in response to server unresponsiveness) in the context
of file system replication, the appropriate handling of state shared of file system replication, the appropriate handling of state shared
between the client and server (i.e. locks, leases, stateid's, and between the client and server (i.e. locks, leases, stateid's, and
Draft Specification NFS version 4 Protocol July 2002
clientid's) is as described below. The handling differs between clientid's) is as described below. The handling differs between
migration and replication. For related discussion of file server migration and replication. For related discussion of file server
state and recover of such see the sections under "File Locking and state and recover of such see the sections under "File Locking and
Share Reservations" Share Reservations"
8.13.1. Migration and State 8.13.1. Migration and State
In the case of migration, the servers involved in the migration of a In the case of migration, the servers involved in the migration of a
file system SHOULD transfer all server state from the original to the file system SHOULD transfer all server state from the original to the
new server. This must be done in a way that is transparent to the new server. This must be done in a way that is transparent to the
skipping to change at page 71, line 4 skipping to change at page 72, line 50
client must be prepared to receive either NFS4ERR_STALE_CLIENTID or client must be prepared to receive either NFS4ERR_STALE_CLIENTID or
NFS4ERR_STALE_STATEID from the new server. The client should then NFS4ERR_STALE_STATEID from the new server. The client should then
recover its state information as it normally would in response to a recover its state information as it normally would in response to a
server failure. The new server must take care to allow for the server failure. The new server must take care to allow for the
recovery of state information as it would in the event of server recovery of state information as it would in the event of server
restart. restart.
8.13.2. Replication and State 8.13.2. Replication and State
Since client switch-over in the case of replication is not under Since client switch-over in the case of replication is not under
Draft Specification NFS version 4 Protocol November 2001
server control, the handling of state is different. In this case, server control, the handling of state is different. In this case,
leases, stateid's and clientid's do not have validity across a leases, stateid's and clientid's do not have validity across a
transition from one server to another. The client must re-establish transition from one server to another. The client must re-establish
its locks on the new server. This can be compared to the re- its locks on the new server. This can be compared to the re-
establishment of locks by means of reclaim-type requests after a establishment of locks by means of reclaim-type requests after a
server reboot. The difference is that the server has no provision to server reboot. The difference is that the server has no provision to
distinguish requests reclaiming locks from those obtaining new locks distinguish requests reclaiming locks from those obtaining new locks
Draft Specification NFS version 4 Protocol July 2002
or to defer the latter. Thus, a client re-establishing a lock on the or to defer the latter. Thus, a client re-establishing a lock on the
new server (by means of a LOCK or OPEN request), may have the new server (by means of a LOCK or OPEN request), may have the
requests denied due to a conflicting lock. Since replication is requests denied due to a conflicting lock. Since replication is
intended for read-only use of filesystems, such denial of locks intended for read-only use of filesystems, such denial of locks
should not pose large difficulties in practice. When an attempt to should not pose large difficulties in practice. When an attempt to
re-establish a lock on a new server is denied, the client should re-establish a lock on a new server is denied, the client should
treat the situation as if his original lock had been revoked. treat the situation as if his original lock had been revoked.
8.13.3. Notification of Migrated Lease 8.13.3. Notification of Migrated Lease
skipping to change at page 72, line 5 skipping to change at page 74, line 5
perform some operation, such as a RENEW, on each file system perform some operation, such as a RENEW, on each file system
associated with the server in question. When the client receives an associated with the server in question. When the client receives an
NFS4ERR_MOVED error, the client can follow the normal process to NFS4ERR_MOVED error, the client can follow the normal process to
obtain the new server information (through the fs_locations obtain the new server information (through the fs_locations
attribute) and perform renewal of those leases on the new server. If attribute) and perform renewal of those leases on the new server. If
the server has not had state transferred to it transparently, it will the server has not had state transferred to it transparently, it will
receive either NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from receive either NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from
the new server, as described above, and can then recover state the new server, as described above, and can then recover state
information as it does in the event of server failure. information as it does in the event of server failure.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
9. Client-Side Caching 9. Client-Side Caching
Client-side caching of data, of file attributes, and of file names is Client-side caching of data, of file attributes, and of file names is
essential to providing good performance with the NFS protocol. essential to providing good performance with the NFS protocol.
Providing distributed cache coherence is a difficult problem and Providing distributed cache coherence is a difficult problem and
previous versions of the NFS protocol have not attempted it. previous versions of the NFS protocol have not attempted it.
Instead, several NFS client implementation techniques have been used Instead, several NFS client implementation techniques have been used
to reduce the problems that a lack of coherence poses for users. to reduce the problems that a lack of coherence poses for users.
These techniques have not been clearly defined by earlier protocol These techniques have not been clearly defined by earlier protocol
skipping to change at page 73, line 5 skipping to change at page 75, line 5
performance is to allow a client that repeatedly opens a file to do performance is to allow a client that repeatedly opens a file to do
so without reference to the server. This is done until potentially so without reference to the server. This is done until potentially
conflicting operations from another client actually occur. conflicting operations from another client actually occur.
A similar situation arises in connection with file locking. Sending A similar situation arises in connection with file locking. Sending
file lock and unlock requests to the server as well as the read and file lock and unlock requests to the server as well as the read and
write requests necessary to make data caching consistent with the write requests necessary to make data caching consistent with the
locking semantics (see the section "Data Caching and File Locking") locking semantics (see the section "Data Caching and File Locking")
can severely limit performance. When locking is used to provide can severely limit performance. When locking is used to provide
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
protection against infrequent conflicts, a large penalty is incurred. protection against infrequent conflicts, a large penalty is incurred.
This penalty may discourage the use of file locking by applications. This penalty may discourage the use of file locking by applications.
The NFS version 4 protocol provides more aggressive caching The NFS version 4 protocol provides more aggressive caching
strategies with the following design goals: strategies with the following design goals:
o Compatibility with a large range of server semantics. o Compatibility with a large range of server semantics.
o Provide the same caching benefits as previous versions of the o Provide the same caching benefits as previous versions of the
skipping to change at page 74, line 5 skipping to change at page 76, line 5
on them. Preliminary testing of callback functionality by means of a on them. Preliminary testing of callback functionality by means of a
CB_NULL procedure determines whether callbacks can be supported. The CB_NULL procedure determines whether callbacks can be supported. The
CB_NULL procedure checks the continuity of the callback path. A CB_NULL procedure checks the continuity of the callback path. A
server makes a preliminary assessment of callback availability to a server makes a preliminary assessment of callback availability to a
given client and avoids delegating responsibilities until it has given client and avoids delegating responsibilities until it has
determined that callbacks are supported. Because the granting of a determined that callbacks are supported. Because the granting of a
delegation is always conditional upon the absence of conflicting delegation is always conditional upon the absence of conflicting
access, clients must not assume that a delegation will be granted and access, clients must not assume that a delegation will be granted and
they must always be prepared for OPENs to be processed without any they must always be prepared for OPENs to be processed without any
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
delegations being granted. delegations being granted.
Once granted, a delegation behaves in most ways like a lock. There Once granted, a delegation behaves in most ways like a lock. There
is an associated lease that is subject to renewal together with all is an associated lease that is subject to renewal together with all
of the other leases held by that client. of the other leases held by that client.
Unlike locks, an operation by a second client to a delegated file Unlike locks, an operation by a second client to a delegated file
will cause the server to recall a delegation through a callback. will cause the server to recall a delegation through a callback.
skipping to change at page 75, line 5 skipping to change at page 77, line 5
There are three situations that delegation recovery must deal with: There are three situations that delegation recovery must deal with:
o Client reboot or restart o Client reboot or restart
o Server reboot or restart o Server reboot or restart
o Network partition (full or callback-only) o Network partition (full or callback-only)
In the event the client reboots or restarts, the failure to renew In the event the client reboots or restarts, the failure to renew
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
leases will result in the revocation of record locks and share leases will result in the revocation of record locks and share
reservations. Delegations, however, may be treated a bit reservations. Delegations, however, may be treated a bit
differently. differently.
There will be situations in which delegations will need to be There will be situations in which delegations will need to be
reestablished after a client reboots or restarts. The reason for reestablished after a client reboots or restarts. The reason for
this is the client may have file data stored locally and this data this is the client may have file data stored locally and this data
was associated with the previously held delegations. The client will was associated with the previously held delegations. The client will
need to reestablish the appropriate file state on the server. need to reestablish the appropriate file state on the server.
skipping to change at page 76, line 5 skipping to change at page 78, line 5
are to be continued. are to be continued.
o The use of callbacks is not to be depended upon until the client o The use of callbacks is not to be depended upon until the client
has proven its ability to receive them. has proven its ability to receive them.
When a network partition occurs, delegations are subject to freeing When a network partition occurs, delegations are subject to freeing
by the server when the lease renewal period expires. This is similar by the server when the lease renewal period expires. This is similar
to the behavior for locks and share reservations. For delegations, to the behavior for locks and share reservations. For delegations,
however, the server may extend the period in which conflicting however, the server may extend the period in which conflicting
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
requests are held off. Eventually the occurrence of a conflicting requests are held off. Eventually the occurrence of a conflicting
request from another client will cause revocation of the delegation. request from another client will cause revocation of the delegation.
A loss of the callback path (e.g. by later network configuration A loss of the callback path (e.g. by later network configuration
change) will have the same effect. A recall request will fail and change) will have the same effect. A recall request will fail and
revocation of the delegation will result. revocation of the delegation will result.
A client normally finds out about revocation of a delegation when it A client normally finds out about revocation of a delegation when it
uses a stateid associated with a delegation and receives the error uses a stateid associated with a delegation and receives the error
NFS4ERR_EXPIRED. It also may find out about delegation revocation NFS4ERR_EXPIRED. It also may find out about delegation revocation
skipping to change at page 77, line 5 skipping to change at page 79, line 5
data to applications or modify it on behalf of an application when it data to applications or modify it on behalf of an application when it
would not be valid to obtain or modify that same data via a READ or would not be valid to obtain or modify that same data via a READ or
WRITE operation. WRITE operation.
Furthermore, in the absence of open delegation (see the section "Open Furthermore, in the absence of open delegation (see the section "Open
Delegation") two additional rules apply. Note that these rules are Delegation") two additional rules apply. Note that these rules are
obeyed in practice by many NFS version 2 and version 3 clients. obeyed in practice by many NFS version 2 and version 3 clients.
o First, cached data present on a client must be revalidated after o First, cached data present on a client must be revalidated after
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
doing an OPEN. This is to ensure that the data for the OPENed doing an OPEN. This is to ensure that the data for the OPENed
file is still correctly reflected in the client's cache. This file is still correctly reflected in the client's cache. This
validation must be done at least when the client's OPEN validation must be done at least when the client's OPEN
operation includes DENY=WRITE or BOTH thus terminating a period operation includes DENY=WRITE or BOTH thus terminating a period
in which other clients may have had the opportunity to open the in which other clients may have had the opportunity to open the
file with WRITE access. Clients may choose to do the file with WRITE access. Clients may choose to do the
revalidation more often (i.e. at OPENs specifying DENY=NONE) to revalidation more often (i.e. at OPENs specifying DENY=NONE) to
parallel the NFS version 3 protocol's practice for the benefit parallel the NFS version 3 protocol's practice for the benefit
of users assuming this degree of cache revalidation. of users assuming this degree of cache revalidation.
skipping to change at page 78, line 5 skipping to change at page 80, line 5
o First, when a client obtains a file lock for a particular o First, when a client obtains a file lock for a particular
region, the data cache corresponding to that region (if any region, the data cache corresponding to that region (if any
cache data exists) must be revalidated. If the change attribute cache data exists) must be revalidated. If the change attribute
indicates that the file may have been updated since the cached indicates that the file may have been updated since the cached
data was obtained, the client must flush or invalidate the data was obtained, the client must flush or invalidate the
cached data for the newly locked region. A client might choose cached data for the newly locked region. A client might choose
to invalidate all of non-modified cached data that it has for to invalidate all of non-modified cached data that it has for
the file but the only requirement for correct operation is to the file but the only requirement for correct operation is to
invalidate all of the data in the newly locked region. invalidate all of the data in the newly locked region.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
o Second, before releasing a write lock for a region, all modified o Second, before releasing a write lock for a region, all modified
data for that region must be flushed to the server. The data for that region must be flushed to the server. The
modified data must also be written to stable storage. modified data must also be written to stable storage.
Note that flushing data to the server and the invalidation of cached Note that flushing data to the server and the invalidation of cached
data must reflect the actual byte ranges locked or unlocked. data must reflect the actual byte ranges locked or unlocked.
Rounding these up or down to reflect client cache block boundaries Rounding these up or down to reflect client cache block boundaries
will cause problems if not carefully done. For example, writing a will cause problems if not carefully done. For example, writing a
modified block when only half of that block is within an area being modified block when only half of that block is within an area being
skipping to change at page 79, line 5 skipping to change at page 81, line 5
areas covered by an appropriate record lock and those for which there areas covered by an appropriate record lock and those for which there
are modifications not covered by a record lock. Any writes done for are modifications not covered by a record lock. Any writes done for
the former class of files must not include areas not locked and thus the former class of files must not include areas not locked and thus
not modified on the client. not modified on the client.
9.3.3. Data Caching and Mandatory File Locking 9.3.3. Data Caching and Mandatory File Locking
Client side data caching needs to respect mandatory file locking when Client side data caching needs to respect mandatory file locking when
it is in effect. The presence of mandatory file locking for a given it is in effect. The presence of mandatory file locking for a given
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
file is indicated in the result flags for an OPEN. When mandatory file is indicated in the result flags for an OPEN. When mandatory
locking is in effect for a file, the client must check for an locking is in effect for a file, the client must check for an
appropriate file lock for data being read or written. If a lock appropriate file lock for data being read or written. If a lock
exists for the range being read or written, the client may satisfy exists for the range being read or written, the client may satisfy
the request using the client's validated cache. If an appropriate the request using the client's validated cache. If an appropriate
file lock is not held for the range of the read or write, the read or file lock is not held for the range of the read or write, the read or
write request must not be satisfied by the client's cache and the write request must not be satisfied by the client's cache and the
request must be sent to the server for processing. When a read or request must be sent to the server for processing. When a read or
write request partially overlaps a locked region, the request should write request partially overlaps a locked region, the request should
skipping to change at page 80, line 5 skipping to change at page 82, line 5
the same server side object: the same server side object:
o If GETATTR directed to two filehandles have different values of o If GETATTR directed to two filehandles have different values of
the fsid attribute, then the filehandles represent distinct the fsid attribute, then the filehandles represent distinct
objects. objects.
o If GETATTR for any file with an fsid that matches the fsid of o If GETATTR for any file with an fsid that matches the fsid of
the two filehandles in question returns a unique_handles the two filehandles in question returns a unique_handles
attribute with a value of TRUE, then the two objects are attribute with a value of TRUE, then the two objects are
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
distinct. distinct.
o If GETATTR directed to the two filehandles does not return the o If GETATTR directed to the two filehandles does not return the
fileid attribute for one or both of the handles, then the it fileid attribute for one or both of the handles, then it cannot
cannot be determined whether the two objects are the same. be determined whether the two objects are the same. Therefore,
Therefore, operations which depend on that knowledge (e.g. operations which depend on that knowledge (e.g. client side data
client side data caching) cannot be done reliably. caching) cannot be done reliably.
o If GETATTR directed to the two filehandles returns different o If GETATTR directed to the two filehandles returns different
values for the fileid attribute, then they are distinct objects. values for the fileid attribute, then they are distinct objects.
o Otherwise they are the same object. o Otherwise they are the same object.
9.4. Open Delegation 9.4. Open Delegation
When a file is being OPENed, the server may delegate further handling When a file is being OPENed, the server may delegate further handling
of opens and closes for that file to the opening client. Any such of opens and closes for that file to the opening client. Any such
skipping to change at page 81, line 5 skipping to change at page 83, line 5
o The existence of any server-specific semantics of OPEN/CLOSE o The existence of any server-specific semantics of OPEN/CLOSE
that would make the required handling incompatible with the that would make the required handling incompatible with the
prescribed handling that the delegated client would apply (see prescribed handling that the delegated client would apply (see
below). below).
There are two types of open delegations, read and write. A read open There are two types of open delegations, read and write. A read open
delegation allows a client to handle, on its own, requests to open a delegation allows a client to handle, on its own, requests to open a
file for reading that do not deny read access to others. Multiple file for reading that do not deny read access to others. Multiple
read open delegations may be outstanding simultaneously and do not read open delegations may be outstanding simultaneously and do not
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
conflict. A write open delegation allows the client to handle, on conflict. A write open delegation allows the client to handle, on
its own, all opens. Only one write open delegation may exist for a its own, all opens. Only one write open delegation may exist for a
given file at a given time and it is inconsistent with any read open given file at a given time and it is inconsistent with any read open
delegations. delegations.
When a client has a read open delegation, it may not make any changes When a client has a read open delegation, it may not make any changes
to the contents or attributes of the file but it is assured that no to the contents or attributes of the file but it is assured that no
other client may do so. When a client has a write open delegation, other client may do so. When a client has a write open delegation,
it may modify the file data since no other client will be accessing it may modify the file data since no other client will be accessing
the file's data. The client holding a write delegation may only the file's data. The client holding a write delegation may only
affect file attributes which are intimately connected with the file affect file attributes which are intimately connected with the file
data: object_size, time_modify, change. data: size, time_modify, change.
When a client has an open delegation, it does not send OPENs or When a client has an open delegation, it does not send OPENs or
CLOSEs to the server but updates the appropriate status internally. CLOSEs to the server but updates the appropriate status internally.
For a read open delegation, opens that cannot be handled locally For a read open delegation, opens that cannot be handled locally
(opens for write or that deny read access) must be sent to the (opens for write or that deny read access) must be sent to the
server. server.
When an open delegation is made, the response to the OPEN contains an When an open delegation is made, the response to the OPEN contains an
open delegation structure which specifies the following: open delegation structure which specifies the following:
skipping to change at page 82, line 5 skipping to change at page 84, line 5
being denied so that the checks can be made by the server itself. being denied so that the checks can be made by the server itself.
o The access and deny bits for the request and the file as o The access and deny bits for the request and the file as
described in the section "Share Reservations". described in the section "Share Reservations".
o The read and write permissions as determined below. o The read and write permissions as determined below.
The nfsace4 passed with delegation can be used to avoid frequent The nfsace4 passed with delegation can be used to avoid frequent
ACCESS calls. The permission check should be as follows: ACCESS calls. The permission check should be as follows:
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
o If the nfsace4 indicates that the open may be done, then it o If the nfsace4 indicates that the open may be done, then it
should be granted without reference to the server. should be granted without reference to the server.
o If the nfsace4 indicates that the open may not be done, then an o If the nfsace4 indicates that the open may not be done, then an
ACCESS request must be sent to the server to obtain the ACCESS request must be sent to the server to obtain the
definitive answer. definitive answer.
The server may return an nfsace4 that is more restrictive than the The server may return an nfsace4 that is more restrictive than the
actual ACL of the file. This includes an nfsace4 that specifies actual ACL of the file. This includes an nfsace4 that specifies
skipping to change at page 83, line 5 skipping to change at page 85, line 5
Therefore, READs or WRITEs with a special stateid done by another Therefore, READs or WRITEs with a special stateid done by another
client will force the server to recall a write open delegation. A client will force the server to recall a write open delegation. A
WRITE with a special stateid done by another client will force a WRITE with a special stateid done by another client will force a
recall of read open delegations. recall of read open delegations.
With delegations, a client is able to avoid writing data to the With delegations, a client is able to avoid writing data to the
server when the CLOSE of a file is serviced. The CLOSE operation is server when the CLOSE of a file is serviced. The CLOSE operation is
the usual point at which the client is notified of a lack of stable the usual point at which the client is notified of a lack of stable
storage for the modified file data generated by the application. At storage for the modified file data generated by the application. At
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
the CLOSE, file data is written to the server and through normal the CLOSE, file data is written to the server and through normal
accounting the server is able to determine if the available file accounting the server is able to determine if the available file
system space for the data has been exceeded (i.e. server returns system space for the data has been exceeded (i.e. server returns
NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas.
The introduction of delegations requires that a alternative method be The introduction of delegations requires that a alternative method be
in place for the same type of communication to occur between client in place for the same type of communication to occur between client
and server. and server.
In the delegation response, the server provides either the limit of In the delegation response, the server provides either the limit of
skipping to change at page 84, line 5 skipping to change at page 86, line 5
locking. This can be done since the delegation implies that there locking. This can be done since the delegation implies that there
can be no conflicting locks. Similarly, all of the revalidations can be no conflicting locks. Similarly, all of the revalidations
that would normally be associated with obtaining locks and the that would normally be associated with obtaining locks and the
flushing of data associated with the releasing of locks need not be flushing of data associated with the releasing of locks need not be
done. done.
9.4.3. Recall of Open Delegation 9.4.3. Recall of Open Delegation
The following events necessitate recall of an open delegation: The following events necessitate recall of an open delegation:
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
o Potentially conflicting OPEN request (or READ/WRITE done with o Potentially conflicting OPEN request (or READ/WRITE done with
"special" stateid) "special" stateid)
o SETATTR issued by another client o SETATTR issued by another client
o REMOVE request for the file o REMOVE request for the file
o RENAME request for the file as either source or target of the o RENAME request for the file as either source or target of the
RENAME RENAME
skipping to change at page 84, line 33 skipping to change at page 86, line 33
In addition to the situations above, the server may choose to recall In addition to the situations above, the server may choose to recall
open delegations at any time if resource constraints make it open delegations at any time if resource constraints make it
advisable to do so. Clients should always be prepared for the advisable to do so. Clients should always be prepared for the
possibility of recall. possibility of recall.
The server needs to employ special handling for a GETATTR where the The server needs to employ special handling for a GETATTR where the
target is a file that has a write open delegation in effect. In this target is a file that has a write open delegation in effect. In this
case, the client holding the delegation needs to be interrogated. case, the client holding the delegation needs to be interrogated.
The server will use a CB_GETATTR callback, if the GETATTR attribute The server will use a CB_GETATTR callback, if the GETATTR attribute
bits include any of the attributes that a write open delegate may bits include any of the attributes that a write open delegate may
modify (object_size, time_modify, change). modify (size, time_modify, change).
When a client receives a recall for an open delegation, it needs to When a client receives a recall for an open delegation, it needs to
update state on the server before returning the delegation. These update state on the server before returning the delegation. These
same updates must be done whenever a client chooses to return a same updates must be done whenever a client chooses to return a
delegation voluntarily. The following items of state need to be delegation voluntarily. The following items of state need to be
dealt with: dealt with:
o If the file associated with the delegation is no longer open and o If the file associated with the delegation is no longer open and
no previous CLOSE operation has been sent to the server, a CLOSE no previous CLOSE operation has been sent to the server, a CLOSE
operation must be sent to the server. operation must be sent to the server.
skipping to change at page 85, line 5 skipping to change at page 87, line 5
OPEN requests are done with the claim type of OPEN requests are done with the claim type of
CLAIM_DELEGATE_CUR. This will allow the presentation of the CLAIM_DELEGATE_CUR. This will allow the presentation of the
delegation stateid so that the client can establish the delegation stateid so that the client can establish the
appropriate rights to perform the OPEN. (see the section appropriate rights to perform the OPEN. (see the section
"Operation 18: OPEN" for details.) "Operation 18: OPEN" for details.)
o If there are granted file locks, the corresponding LOCK o If there are granted file locks, the corresponding LOCK
operations need to be performed. This applies to the write open operations need to be performed. This applies to the write open
delegation case only. delegation case only.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
o For a write open delegation, if at the time of recall the file o For a write open delegation, if at the time of recall the file
is not open for write, all modified data for the file must be is not open for write, all modified data for the file must be
flushed to the server. If the delegation had not existed, the flushed to the server. If the delegation had not existed, the
client would have done this data flush before the CLOSE client would have done this data flush before the CLOSE
operation. operation.
o For a write open delegation when a file is still open at the o For a write open delegation when a file is still open at the
time of recall, any modified data for the file needs to be time of recall, any modified data for the file needs to be
flushed to the server. flushed to the server.
o With the write open delegation in place, it is possible that the o With the write open delegation in place, it is possible that the
file was truncated during the duration of the delegation. For file was truncated during the duration of the delegation. For
example, the truncation could have occurred as a result of an example, the truncation could have occurred as a result of an
OPEN UNCHECKED with a object_size attribute value of zero. OPEN UNCHECKED with a size attribute value of zero. Therefore,
Therefore, if a truncation of the file has occurred and this if a truncation of the file has occurred and this operation has
operation has not been propagated to the server, the truncation not been propagated to the server, the truncation must occur
must occur before any modified data is written to the server. before any modified data is written to the server.
In the case of write open delegation, file locking imposes some In the case of write open delegation, file locking imposes some
additional requirements. The flushing of any modified data in any additional requirements. The flushing of any modified data in any
region for which a write lock was released while the write open region for which a write lock was released while the write open
delegation was in effect is what is required to precisely maintain delegation was in effect is what is required to precisely maintain
the associated invariant. However, because the write open delegation the associated invariant. However, because the write open delegation
implies no other locking by other clients, a simpler implementation implies no other locking by other clients, a simpler implementation
is to flush all modified data for the file (as described just above) is to flush all modified data for the file (as described just above)
if any write lock has been released while the write open delegation if any write lock has been released while the write open delegation
was in effect. was in effect.
skipping to change at page 86, line 5 skipping to change at page 88, line 5
Recovery for Write Open Delegation" for additional details. Recovery for Write Open Delegation" for additional details.
9.5. Data Caching and Revocation 9.5. Data Caching and Revocation
When locks and delegations are revoked, the assumptions upon which When locks and delegations are revoked, the assumptions upon which
successful caching depend are no longer guaranteed. The owner of the successful caching depend are no longer guaranteed. The owner of the
locks or share reservations which have been revoked needs to be locks or share reservations which have been revoked needs to be
notified. This notification includes applications with a file open notified. This notification includes applications with a file open
that has a corresponding delegation which has been revoked. Cached that has a corresponding delegation which has been revoked. Cached
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
data associated with the revocation must be removed from the client. data associated with the revocation must be removed from the client.
In the case of modified data existing in the client's cache, that In the case of modified data existing in the client's cache, that
data must be removed from the client without it being written to the data must be removed from the client without it being written to the
server. As mentioned, the assumptions made by the client are no server. As mentioned, the assumptions made by the client are no
longer valid at the point when a lock or delegation has been revoked. longer valid at the point when a lock or delegation has been revoked.
For example, another client may have been granted a conflicting lock For example, another client may have been granted a conflicting lock
after the revocation of the lock at the first client. Therefore, the after the revocation of the lock at the first client. Therefore, the
data within the lock range may have been modified by the other data within the lock range may have been modified by the other
client. Obviously, the first client is unable to guarantee to the client. Obviously, the first client is unable to guarantee to the
skipping to change at page 87, line 5 skipping to change at page 89, line 5
name in the file system name space to ease recovery. Unless the name in the file system name space to ease recovery. Unless the
client can determine that the file has not modified by any other client can determine that the file has not modified by any other
client, this technique must be limited to situations in which a client, this technique must be limited to situations in which a
client has a complete cached copy of the file in question. Use of client has a complete cached copy of the file in question. Use of
such a technique may be limited to files under a certain size or may such a technique may be limited to files under a certain size or may
only be used when sufficient disk space is guaranteed to be available only be used when sufficient disk space is guaranteed to be available
within the target file system and when the client has sufficient within the target file system and when the client has sufficient
buffering resources to keep the cached copy available until it is buffering resources to keep the cached copy available until it is
properly stored to the target file system. properly stored to the target file system.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
9.6. Attribute Caching 9.6. Attribute Caching
The attributes discussed in this section do not include named The attributes discussed in this section do not include named
attributes. Individual named attributes are analogous to files and attributes. Individual named attributes are analogous to files and
caching of the data for these needs to be handled just as data caching of the data for these needs to be handled just as data
caching is for ordinary files. Similarly, LOOKUP results from an caching is for ordinary files. Similarly, LOOKUP results from an
OPENATTR directory are to be cached on the same basis as any other OPENATTR directory are to be cached on the same basis as any other
pathnames and similarly for directory contents. pathnames and similarly for directory contents.
Clients may cache file attributes obtained from the server and use Clients may cache file attributes obtained from the server and use
them to avoid subsequent GETATTR requests. Such caching is write them to avoid subsequent GETATTR requests. Such caching is write
through in that modification to file attributes is always done by through in that modification to file attributes is always done by
means of requests to the server and should not be done locally and means of requests to the server and should not be done locally and
cached. The exception to this are modifications to attributes that cached. The exception to this are modifications to attributes that
are intimately connected with data caching. Therefore, extending a are intimately connected with data caching. Therefore, extending a
file by writing data to the local data cache is reflected immediately file by writing data to the local data cache is reflected immediately
in the object_size as seen on the client without this change being in the size as seen on the client without this change being
immediately reflected on the server. Normally such changes are not immediately reflected on the server. Normally such changes are not
propagated directly to the server but when the modified data is propagated directly to the server but when the modified data is
flushed to the server, analogous attribute changes are made on the flushed to the server, analogous attribute changes are made on the
server. When open delegation is in effect, the modified attributes server. When open delegation is in effect, the modified attributes
may be returned to the server in the response to a CB_RECALL call. may be returned to the server in the response to a CB_RECALL call.
The result of local caching of attributes is that the attribute The result of local caching of attributes is that the attribute
caches maintained on individual clients will not be coherent. Changes caches maintained on individual clients will not be coherent. Changes
made in one order on the server may be seen in a different order on made in one order on the server may be seen in a different order on
one client and in a third order on a different client. one client and in a third order on a different client.
skipping to change at page 88, line 5 skipping to change at page 90, line 5
server, the updated attribute set is requested as part of the server, the updated attribute set is requested as part of the
containing RPC. This includes directory operations that update containing RPC. This includes directory operations that update
attributes indirectly. This is accomplished by following the attributes indirectly. This is accomplished by following the
modifying operation with a GETATTR operation and then using the modifying operation with a GETATTR operation and then using the
results of the GETATTR to update the client's cached attributes. results of the GETATTR to update the client's cached attributes.
Note that if the full set of attributes to be cached is requested by Note that if the full set of attributes to be cached is requested by
READDIR, the results can be cached by the client on the same basis as READDIR, the results can be cached by the client on the same basis as
attributes obtained via GETATTR. attributes obtained via GETATTR.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
A client may validate its cached version of attributes for a file by A client may validate its cached version of attributes for a file by
fetching only the change attribute and assuming that if the change fetching only the change attribute and assuming that if the change
attribute has the same value as it did when the attributes were attribute has the same value as it did when the attributes were
cached, then no attributes have changed. The possible exception is cached, then no attributes have changed. The possible exception is
the attribute time_access. the attribute time_access.
9.7. Name Caching 9.7. Name Caching
The results of LOOKUP and READDIR operations may be cached to avoid The results of LOOKUP and READDIR operations may be cached to avoid
skipping to change at page 89, line 5 skipping to change at page 91, line 5
indicates no modification, the name cache can be updated on the indicates no modification, the name cache can be updated on the
client to reflect the directory operation and the associated timeout client to reflect the directory operation and the associated timeout
extended. The post-operation change value needs to be saved as the extended. The post-operation change value needs to be saved as the
basis for future change_info4 comparisons. basis for future change_info4 comparisons.
As demonstrated by the scenario above, name caching requires that the As demonstrated by the scenario above, name caching requires that the
client revalidate name cache data by inspecting the change attribute client revalidate name cache data by inspecting the change attribute
of a directory at the point when the name cache item was cached. of a directory at the point when the name cache item was cached.
This requires that the server update the change attribute for This requires that the server update the change attribute for
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
directories when the contents of the corresponding directory is directories when the contents of the corresponding directory is
modified. For a client to use the change_info4 information modified. For a client to use the change_info4 information
appropriately and correctly, the server must report the pre and post appropriately and correctly, the server must report the pre and post
operation change attribute values atomically. When the server is operation change attribute values atomically. When the server is
unable to report the before and after values atomically with respect unable to report the before and after values atomically with respect
to the directory operation, the server must indicate that fact in the to the directory operation, the server must indicate that fact in the
change_info4 return value. When the information is not atomically change_info4 return value. When the information is not atomically
reported, the client should not assume that other clients have not reported, the client should not assume that other clients have not
changed the directory. changed the directory.
skipping to change at page 90, line 5 skipping to change at page 92, line 5
This requires that the server update the change attribute for This requires that the server update the change attribute for
directories when the contents of the corresponding directory is directories when the contents of the corresponding directory is
modified. For a client to use the change_info4 information modified. For a client to use the change_info4 information
appropriately and correctly, the server must report the pre and post appropriately and correctly, the server must report the pre and post
operation change attribute values atomically. When the server is operation change attribute values atomically. When the server is
unable to report the before and after values atomically with respect unable to report the before and after values atomically with respect
to the directory operation, the server must indicate that fact in the to the directory operation, the server must indicate that fact in the
change_info4 return value. When the information is not atomically change_info4 return value. When the information is not atomically
reported, the client should not assume that other clients have not reported, the client should not assume that other clients have not
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
changed the directory. changed the directory.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
10. Minor Versioning 10. Minor Versioning
To address the requirement of an NFS protocol that can evolve as the To address the requirement of an NFS protocol that can evolve as the
need arises, the NFS version 4 protocol contains the rules and need arises, the NFS version 4 protocol contains the rules and
framework to allow for future minor changes or versioning. framework to allow for future minor changes or versioning.
The base assumption with respect to minor versioning is that any The base assumption with respect to minor versioning is that any
future accepted minor version must follow the IETF process and be future accepted minor version must follow the IETF process and be
documented in a standards track RFC. Therefore, each minor version documented in a standards track RFC. Therefore, each minor version
skipping to change at page 92, line 5 skipping to change at page 94, line 5
documented attribute. documented attribute.
Since attribute results are specified as an opaque array of Since attribute results are specified as an opaque array of
per-attribute XDR encoded results, the complexity of adding new per-attribute XDR encoded results, the complexity of adding new
attributes in the midst of the current definitions will be too attributes in the midst of the current definitions will be too
burdensome. burdensome.
3 Minor versions must not modify the structure of an existing 3 Minor versions must not modify the structure of an existing
operation's arguments or results. operation's arguments or results.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
Again the complexity of handling multiple structure definitions Again the complexity of handling multiple structure definitions
for a single operation is too burdensome. New operations should for a single operation is too burdensome. New operations should
be added instead of modifying existing structures for a minor be added instead of modifying existing structures for a minor
version. version.
This rule does not preclude the following adaptations in a minor This rule does not preclude the following adaptations in a minor
version. version.
o adding bits to flag fields such as new attributes to o adding bits to flag fields such as new attributes to
skipping to change at page 93, line 5 skipping to change at page 95, line 5
the request as an XDR decode error. This approach allows for the request as an XDR decode error. This approach allows for
the obsolescence of an operation while maintaining its structure the obsolescence of an operation while maintaining its structure
so that a future minor version can reintroduce the operation. so that a future minor version can reintroduce the operation.
8.1 Minor versions may declare attributes mandatory to NOT 8.1 Minor versions may declare attributes mandatory to NOT
implement. implement.
8.2 Minor versions may declare flag bits or enumeration values as 8.2 Minor versions may declare flag bits or enumeration values as
mandatory to NOT implement. mandatory to NOT implement.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
9 Minor versions may downgrade features from mandatory to 9 Minor versions may downgrade features from mandatory to
recommended, or recommended to optional. recommended, or recommended to optional.
10 Minor versions may upgrade features from optional to recommended 10 Minor versions may upgrade features from optional to recommended
or recommended to mandatory. or recommended to mandatory.
11 A client and server that support minor version X must support 11 A client and server that support minor version X must support
minor versions 0 (zero) through X-1 as well. minor versions 0 (zero) through X-1 as well.
skipping to change at page 94, line 5 skipping to change at page 96, line 5
This rule allows for the introduction of new functionality and This rule allows for the introduction of new functionality and
forces the use of implementation experience before designating a forces the use of implementation experience before designating a
feature as mandatory. feature as mandatory.
13 A client MUST NOT attempt to use a stateid, file handle, or 13 A client MUST NOT attempt to use a stateid, file handle, or
similar returned object from the COMPOUND procedure with minor similar returned object from the COMPOUND procedure with minor
version X for another COMPOUND procedure with minor version Y, version X for another COMPOUND procedure with minor version Y,
where X != Y. where X != Y.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
11. Internationalization 11. Internationalization
The primary issue in which NFS needs to deal with The primary issue in which NFS needs to deal with
internationalization, or I18N, is with respect to file names and internationalization, or I18N, is with respect to file names and
other strings as used within the protocol. The choice of string other strings as used within the protocol. The choice of string
representation must allow reasonable name/string access to clients representation must allow reasonable name/string access to clients
which use various languages. The UTF-8 encoding of the UCS as which use various languages. The UTF-8 encoding of the UCS as
defined by [ISO10646] allows for this type of access and follows the defined by [ISO10646] allows for this type of access and follows the
policy described in "IETF Policy on Character Sets and Languages", policy described in "IETF Policy on Character Sets and Languages",
skipping to change at page 95, line 5 skipping to change at page 97, line 5
server like: server like:
/component-1/component-2/component-3 /component-1/component-2/component-3
Each component could have been created with a different locale. If Each component could have been created with a different locale. If
one issues CREATE with multi-component path name, and if some of the one issues CREATE with multi-component path name, and if some of the
leading components already exist, what is to be done with the leading components already exist, what is to be done with the
existing components? Is the current locale attribute replaced with existing components? Is the current locale attribute replaced with
the user's current one? These types of situations quickly become too the user's current one? These types of situations quickly become too
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
complex when there is an alternate solution. complex when there is an alternate solution.
If the NFS version 4 protocol used a universal 16 bit or 32 bit If the NFS version 4 protocol used a universal 16 bit or 32 bit
character set (or an encoding of a 16 bit or 32 bit character set character set (or an encoding of a 16 bit or 32 bit character set
into octets), then the server and client need not care if the locale into octets), then the server and client need not care if the locale
of the user accessing the file is different than the locale of the of the user accessing the file is different than the locale of the
user who created the file. The unique 16 bit or 32 bit encoding of user who created the file. The unique 16 bit or 32 bit encoding of
the character allows for determination of what language the character the character allows for determination of what language the character
is from and also how to display that character on the client. The is from and also how to display that character on the client. The
skipping to change at page 96, line 5 skipping to change at page 98, line 5
UCS-4 a four octet per character encoding that permits the UCS-4 a four octet per character encoding that permits the
encoding of up to 2^31 characters. encoding of up to 2^31 characters.
UTF UTF is an abbreviation of the term "UCS transformation UTF UTF is an abbreviation of the term "UCS transformation
format" and is used in the naming of various standards for format" and is used in the naming of various standards for
encoding of UCS characters as described below. encoding of UCS characters as described below.
UTF-1 Only historical interest; it has been removed from 10646-1 UTF-1 Only historical interest; it has been removed from 10646-1
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
UTF-7 Encodes the entire "repertoire" of UCS "characters using UTF-7 Encodes the entire "repertoire" of UCS "characters using
only octets with the higher order bit clear". [RFC2152] only octets with the higher order bit clear". [RFC2152]
describes UTF-7. UTF-7 accomplishes this by reserving one describes UTF-7. UTF-7 accomplishes this by reserving one
of the 7bit US-ASCII characters as a "shift" character to of the 7bit US-ASCII characters as a "shift" character to
indicate non-US-ASCII characters. indicate non-US-ASCII characters.
UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII UTF-8 Unlike UTF-7, uses all 8 bits of the octets. US-ASCII
characters are encoded as before unchanged. Any octet with characters are encoded as before unchanged. Any octet with
the high bit cleared can only mean a US-ASCII character. the high bit cleared can only mean a US-ASCII character.
skipping to change at page 97, line 5 skipping to change at page 99, line 5
UTF-8 solves problems for NFS that exist with the use of UCS and UTF-8 solves problems for NFS that exist with the use of UCS and
Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way Unicode. UTF-8 will encode 16 bit and 32 bit characters in a way
that will be compact for most users. The encoding table from UCS-4 to that will be compact for most users. The encoding table from UCS-4 to
UTF-8, as copied from [RFC2279]: UTF-8, as copied from [RFC2279]:
UCS-4 range (hex.) UTF-8 octet sequence (binary) UCS-4 range (hex.) UTF-8 octet sequence (binary)
0000 0000-0000 007F 0xxxxxxx 0000 0000-0000 007F 0xxxxxxx
0000 0080-0000 07FF 110xxxxx 10xxxxxx 0000 0080-0000 07FF 110xxxxx 10xxxxxx
0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx 0000 0800-0000 FFFF 1110xxxx 10xxxxxx 10xxxxxx
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx 0001 0000-001F FFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 0020 0000-03FF FFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 0400 0000-7FFF FFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
10xxxxxx 10xxxxxx
See [RFC2279] for precise encoding and decoding rules. Note because See [RFC2279] for precise encoding and decoding rules. Note because
of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account of UTF-16, the algorithm from Unicode/UCS-2 to UTF-8 needs to account
for the reserved range between D800 and DFFF. for the reserved range between D800 and DFFF.
skipping to change at page 98, line 5 skipping to change at page 100, line 5
The NFS version 4 protocol does not mandate the use of a particular The NFS version 4 protocol does not mandate the use of a particular
normalization form at this time. A later revision of this normalization form at this time. A later revision of this
specification may specify a particular normalization form. specification may specify a particular normalization form.
Therefore, the server and client can expect that they may receive Therefore, the server and client can expect that they may receive
unnormalized characters within protocol requests and responses. If unnormalized characters within protocol requests and responses. If
the operating environment requires normalization, then the the operating environment requires normalization, then the
implementation must normalize the various UTF-8 encoded strings implementation must normalize the various UTF-8 encoded strings
within the protocol before presenting the information to an within the protocol before presenting the information to an
application (at the client) or local file system (at the server). application (at the client) or local file system (at the server).
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
12. Error Definitions 12. Error Definitions
NFS error numbers are assigned to failed operations within a compound NFS error numbers are assigned to failed operations within a compound
request. A compound request contains a number of NFS operations that request. A compound request contains a number of NFS operations that
have their results encoded in sequence in a compound reply. The have their results encoded in sequence in a compound reply. The
results of successful operations will consist of an NFS4_OK status results of successful operations will consist of an NFS4_OK status
followed by the encoded results of the operation. If an NFS followed by the encoded results of the operation. If an NFS
operation fails, an error status will be entered in the reply and the operation fails, an error status will be entered in the reply and the
compound request will be terminated. compound request will be terminated.
A description of each defined error follows: A description of each defined error follows:
NFS4_OK Indicates the operation completed successfully. NFS4_OK Indicates the operation completed successfully.
NFS4ERR_ACCES Permission denied. The caller does not have the NFS4ERR_ACCESS Permission denied. The caller does not have the
correct permission to perform the requested correct permission to perform the requested
operation. Contrast this with NFS4ERR_PERM, operation. Contrast this with NFS4ERR_PERM,
which restricts itself to owner or privileged which restricts itself to owner or privileged
user permission failures. user permission failures.
NFS4ERR_ATTRNOTSUPP An attribute specified is not supported by the NFS4ERR_ATTRNOTSUPP An attribute specified is not supported by the
server. Does not apply to the GETATTR server. Does not apply to the GETATTR
operation. operation.
NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed NFS4ERR_BADHANDLE Illegal NFS file handle. The file handle failed
internal consistency checks. internal consistency checks.
NFS4ERR_BADOWNER An owner, owner_group, or ACL attribute value
can not be translated to local representation.
NFS4ERR_BADTYPE An attempt was made to create an object of a NFS4ERR_BADTYPE An attempt was made to create an object of a
type not supported by the server. type not supported by the server.
NFS4ERR_BAD_COOKIE READDIR cookie is stale. NFS4ERR_BAD_COOKIE READDIR cookie is stale.
NFS4ERR_BAD_SEQID The sequence number in a locking request is NFS4ERR_BAD_SEQID The sequence number in a locking request is
neither the next expected number or the last neither the next expected number or the last
number processed. number processed.
NFS4ERR_BAD_STATEID A stateid generated by the current server NFS4ERR_BAD_STATEID A stateid generated by the current server
instance, but which does not designate any instance, but which does not designate any
locking state (either current or superseded) locking state (either current or superseded)
for a current lockowner-file pair, was used. for a current lockowner-file pair, was used.
NFS4ERR_BADXDR The server encountered an XDR decoding error NFS4ERR_BADXDR The server encountered an XDR decoding error
while processing an operation. while processing an operation.
NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a NFS4ERR_CLID_INUSE The SETCLIENTID procedure has found that a
client id is already in use by another client. client id is already in use by another client.
Draft Specification NFS version 4 Protocol July 2002
NFS4ERR_DELAY The server initiated the request, but was not NFS4ERR_DELAY The server initiated the request, but was not
able to complete it in a timely fashion. The able to complete it in a timely fashion. The
client should wait and then try the request client should wait and then try the request
Draft Specification NFS version 4 Protocol November 2001
with a new RPC transaction ID. For example, with a new RPC transaction ID. For example,
this error should be returned from a server this error should be returned from a server
that supports hierarchical storage and receives that supports hierarchical storage and receives
a request to process a file that has been a request to process a file that has been
migrated. In this case, the server should start migrated. In this case, the server should start
the immigration process and respond to client the immigration process and respond to client
with this error. This error may also occur with this error. This error may also occur
when a necessary delegation recall makes when a necessary delegation recall makes
processing a request in a timely fashion processing a request in a timely fashion
impossible. impossible.
skipping to change at page 99, line 56 skipping to change at page 102, line 4
server that does not support this operation. server that does not support this operation.
NFS4ERR_IO I/O error. A hard error (for example, a disk NFS4ERR_IO I/O error. A hard error (for example, a disk
error) occurred while processing the requested error) occurred while processing the requested
operation. operation.
NFS4ERR_ISDIR Is a directory. The caller specified a NFS4ERR_ISDIR Is a directory. The caller specified a
directory in a non-directory operation. directory in a non-directory operation.
NFS4ERR_LEASE_MOVED A lease being renewed is associated with a file NFS4ERR_LEASE_MOVED A lease being renewed is associated with a file
system that has been migrated to a new server.
NFS4ERR_LOCKED A read or write operation was attempted on a Draft Specification NFS version 4 Protocol July 2002
Draft Specification NFS version 4 Protocol November 2001 system that has been migrated to a new server.
NFS4ERR_LOCKED A read or write operation was attempted on a
locked file. locked file.
NFS4ERR_LOCK_RANGE A lock request is operating on a sub-range of a NFS4ERR_LOCK_RANGE A lock request is operating on a sub-range of a
current lock for the lock owner and the server current lock for the lock owner and the server
does not support this type of request. does not support this type of request.
NFS4ERR_MINOR_VERS_MISMATCH NFS4ERR_MINOR_VERS_MISMATCH
The server has received a request that The server has received a request that
specifies an unsupported minor version. The specifies an unsupported minor version. The
server must return a COMPOUND4res with a zero server must return a COMPOUND4res with a zero
skipping to change at page 100, line 56 skipping to change at page 103, line 4
state has not been provided to another client. state has not been provided to another client.
NFS4ERR_NOSPC No space left on device. The operation would NFS4ERR_NOSPC No space left on device. The operation would
have caused the server's file system to exceed have caused the server's file system to exceed
its limit. its limit.
NFS4ERR_NOTDIR Not a directory. The caller specified a non- NFS4ERR_NOTDIR Not a directory. The caller specified a non-
directory in a directory operation. directory in a directory operation.
NFS4ERR_NOTEMPTY An attempt was made to remove a directory that NFS4ERR_NOTEMPTY An attempt was made to remove a directory that
Draft Specification NFS version 4 Protocol July 2002
was not empty. was not empty.
NFS4ERR_NOTSUPP Operation is not supported. NFS4ERR_NOTSUPP Operation is not supported.
Draft Specification NFS version 4 Protocol November 2001
NFS4ERR_NOT_SAME This error is returned by the VERIFY operation NFS4ERR_NOT_SAME This error is returned by the VERIFY operation
to signify that the attributes compared were to signify that the attributes compared were
not the same as provided in the client's not the same as provided in the client's
request. request.
NFS4ERR_NXIO I/O error. No such device or address. NFS4ERR_NXIO I/O error. No such device or address.
NFS4ERR_OLD_STATEID A stateid which designates the locking state NFS4ERR_OLD_STATEID A stateid which designates the locking state
for a lockowner-file at an earlier time was for a lockowner-file at an earlier time was
used. used.
NFS4ERR_OPENMODE The client attempted a READ, WRITE, or SETATTR
operation not sanctioned by the stateid passed
(e.g. writing to a file opened only for read).
NFS4ERR_PERM Not owner. The operation was not allowed NFS4ERR_PERM Not owner. The operation was not allowed
because the caller is either not a privileged because the caller is either not a privileged
user (root) or not the owner of the target of user (root) or not the owner of the target of
the operation. the operation.
NFS4ERR_READDIR_NOSPC The encoded response to a READDIR request NFS4ERR_READDIR_NOSPC The encoded response to a READDIR request
exceeds the size limit set by the initial exceeds the size limit set by the initial
request. request.
NFS4ERR_RECLAIM_BAD The reclaim provided by the client does not NFS4ERR_RECLAIM_BAD The reclaim provided by the client does not
skipping to change at page 101, line 51 skipping to change at page 104, line 5
resource exhaustion related to the processing resource exhaustion related to the processing
of the COMPOUND procedure. of the COMPOUND procedure.
NFS4ERR_ROFS Read-only file system. A modifying operation NFS4ERR_ROFS Read-only file system. A modifying operation
was attempted on a read-only file system. was attempted on a read-only file system.
NFS4ERR_SAME This error is returned by the NVERIFY operation NFS4ERR_SAME This error is returned by the NVERIFY operation
to signify that the attributes compared were to signify that the attributes compared were
the same as provided in the client's request. the same as provided in the client's request.
Draft Specification NFS version 4 Protocol July 2002
NFS4ERR_SERVERFAULT An error occurred on the server which does not NFS4ERR_SERVERFAULT An error occurred on the server which does not
map to any of the legal NFS version 4 protocol map to any of the legal NFS version 4 protocol
error values. The client should translate this error values. The client should translate this
into an appropriate error. UNIX clients may into an appropriate error. UNIX clients may
choose to translate this to EIO. choose to translate this to EIO.
NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share NFS4ERR_SHARE_DENIED An attempt to OPEN a file with a share
reservation has failed because of a share reservation has failed because of a share
Draft Specification NFS version 4 Protocol November 2001
conflict. conflict.
NFS4ERR_STALE Invalid file handle. The file handle given in NFS4ERR_STALE Invalid file handle. The file handle given in
the arguments was invalid. The file referred to the arguments was invalid. The file referred to
by that file handle no longer exists or access by that file handle no longer exists or access
to it has been revoked. to it has been revoked.
NFS4ERR_STALE_CLIENTID A clientid not recognized by the server was NFS4ERR_STALE_CLIENTID A clientid not recognized by the server was
used in a locking or SETCLIENTID_CONFIRM used in a locking or SETCLIENTID_CONFIRM
request. request.
skipping to change at page 103, line 5 skipping to change at page 105, line 5
NFS4ERR_TOOSMALL Buffer or request is too small. NFS4ERR_TOOSMALL Buffer or request is too small.
NFS4ERR_WRONGSEC The security mechanism being used by the client NFS4ERR_WRONGSEC The security mechanism being used by the client
for the procedure does not match the server's for the procedure does not match the server's
security policy. The client should change the security policy. The client should change the
security mechanism being used and retry the security mechanism being used and retry the
operation. operation.
NFS4ERR_XDEV Attempt to do a cross-device hard link. NFS4ERR_XDEV Attempt to do a cross-device hard link.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
13. NFS Version 4 Requests 13. NFS Version 4 Requests
For the NFS version 4 RPC program, there are two traditional RPC For the NFS version 4 RPC program, there are two traditional RPC
procedures: NULL and COMPOUND. All other functionality is defined as procedures: NULL and COMPOUND. All other functionality is defined as
a set of operations and these operations are defined in normal a set of operations and these operations are defined in normal
XDR/RPC syntax and semantics. However, these operations are XDR/RPC syntax and semantics. However, these operations are
encapsulated within the COMPOUND procedure. This requires that the encapsulated within the COMPOUND procedure. This requires that the
client combine one or more of the NFS version 4 operations into a client combine one or more of the NFS version 4 operations into a
single request. single request.
skipping to change at page 103, line 42 skipping to change at page 105, line 42
performance within high latency networks. The client can avoid performance within high latency networks. The client can avoid
cumulative latency of multiple RPCs by combining multiple dependent cumulative latency of multiple RPCs by combining multiple dependent
operations into a single COMPOUND procedure. A compound operation operations into a single COMPOUND procedure. A compound operation
may provide for protocol simplification by allowing the client to may provide for protocol simplification by allowing the client to
combine basic procedures into a single request that is customized for combine basic procedures into a single request that is customized for
the client's environment. the client's environment.
The CB_COMPOUND procedure precisely parallels the features of The CB_COMPOUND procedure precisely parallels the features of
COMPOUND as described above. COMPOUND as described above.
The basics of the COMPOUND procedures construction is: The basic structure of the COMPOUND procedure is:
+-----------+-----------+-----------+-- +-----+--------------+--------+-----------+-----------+-----------+--
| op + args | op + args | op + args | | tag | minorversion | numops | op + args | op + args | op + args |
+-----------+-----------+-----------+-- +-----+--------------+--------+-----------+-----------+-----------+--
and the reply looks like this: and the reply's structure is:
+------------+-----------------------+-----------------------+-- +------------+-----+--------+-----------------------+--
|last status | status + op + results | status + op + results | |last status | tag | numres | status + op + results |
+------------+-----------------------+-----------------------+-- +------------+-----+--------+-----------------------+--
13.2. Evaluation of a Compound Request The numops and numres fields, used in the depiction above, represent
the count for the counted array encoding use to signify the number of
arguments or results encoded in the request and response. As per the
XDR encoding, these counts must match exactly the number of operation
The server will process the COMPOUND procedure by evaluating each of Draft Specification NFS version 4 Protocol July 2002
Draft Specification NFS version 4 Protocol November 2001 arguments or results encoded.
13.2. Evaluation of a Compound Request
The server will process the COMPOUND procedure by evaluating each of
the operations within the COMPOUND procedure in order. Each the operations within the COMPOUND procedure in order. Each
component operation consists of a 32 bit operation code, followed by component operation consists of a 32 bit operation code, followed by
the argument of length determined by the type of operation. The the argument of length determined by the type of operation. The
results of each operation are encoded in sequence into a reply results of each operation are encoded in sequence into a reply
buffer. The results of each operation are preceded by the opcode and buffer. The results of each operation are preceded by the opcode and
a status code (normally zero). If an operation results in a non-zero a status code (normally zero). If an operation results in a non-zero
status code, the status will be encoded and evaluation of the status code, the status will be encoded and evaluation of the
compound sequence will halt and the reply will be returned. Note compound sequence will halt and the reply will be returned. Note
that evaluation stops even in the event of "non error" conditions that evaluation stops even in the event of "non error" conditions
such as NFS4ERR_SAME. such as NFS4ERR_SAME.
There are no atomicity requirements for the operations contained There are no atomicity requirements for the operations contained
within the COMPOUND procedure. The operations being evaluated as within the COMPOUND procedure. The operations being evaluated as
part of a COMPOUND request may be evaluated simultaneously with other part of a COMPOUND request may be evaluated simultaneously with other
COMPOUND requests that the server receives. COMPOUND requests that the server receives.
It is the client's responsibility for recovering from any partially It is the client's responsibility for recovering from any partially
completed COMPOUND procedure. Partially completed COMPOUND completed COMPOUND procedure. Partially completed COMPOUND
procedures may occur at any point due to errors such as procedures may occur at any point due to errors such as
NFS4ERR_RESOURCE and NFS4ERR_LONG_DELAY. This may occur even given NFS4ERR_RESOURCE and NFS4ERR_DELAY. This may occur even given an
an otherwise valid operation string. Further, a server reboot which otherwise valid operation string. Further, a server reboot which
occurs in the middle of processing a COMPOUND procedure may leave the occurs in the middle of processing a COMPOUND procedure may leave the
client with the difficult task of determining how far COMPOUND client with the difficult task of determining how far COMPOUND
processing has proceeded. Therefore, the client should avoid overly processing has proceeded. Therefore, the client should avoid overly
complex COMPOUND procedures in the event of the failure of an complex COMPOUND procedures in the event of the failure of an
operation within the procedure. operation within the procedure.
Each operation assumes a "current" and "saved" filehandle that is Each operation assumes a "current" and "saved" filehandle that is
available as part of the execution context of the compound request. available as part of the execution context of the compound request.
Operations may set, change, or return the current filehandle. The Operations may set, change, or return the current filehandle. The
"saved" filehandle is used for temporary storage of a filehandle "saved" filehandle is used for temporary storage of a filehandle
skipping to change at page 104, line 52 skipping to change at page 107, line 4
NFS version 4 operations that modify the file system are synchronous. NFS version 4 operations that modify the file system are synchronous.
When an operation is successfully completed at the server, the client When an operation is successfully completed at the server, the client
can depend that any data associated with the request is now on stable can depend that any data associated with the request is now on stable
storage (the one exception is in the case of the file data in a WRITE storage (the one exception is in the case of the file data in a WRITE
operation with the UNSTABLE option specified). operation with the UNSTABLE option specified).
This implies that any previous operations within the same compound This implies that any previous operations within the same compound
request are also reflected in stable storage. This behavior enables request are also reflected in stable storage. This behavior enables
the client's ability to recover from a partially executed compound the client's ability to recover from a partially executed compound
request which may resulted from the failure of the server. For request which may resulted from the failure of the server. For
Draft Specification NFS version 4 Protocol July 2002
example, if a compound request contains operations A and B and the example, if a compound request contains operations A and B and the
server is unable to send a response to the client, depending on the server is unable to send a response to the client, depending on the
progress the server made in servicing the request the result of both progress the server made in servicing the request the result of both
operations may be reflected in stable storage or just operation A may operations may be reflected in stable storage or just operation A may
be reflected. The server must not have just the results of operation be reflected. The server must not have just the results of operation
B in stable storage. B in stable storage.
Draft Specification NFS version 4 Protocol November 2001
13.4. Operation Values 13.4. Operation Values
The operations encoded in the COMPOUND procedure are identified by The operations encoded in the COMPOUND procedure are identified by
operation values. To avoid overlap with the RPC procedure numbers, operation values. To avoid overlap with the RPC procedure numbers,
operations 0 (zero) and 1 are not defined. Operation 2 is not operations 0 (zero) and 1 are not defined. Operation 2 is not
defined but reserved for future use with minor versioning. defined but reserved for future use with minor versioning.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14. NFS Version 4 Procedures 14. NFS Version 4 Procedures
14.1. Procedure 0: NULL - No Operation 14.1. Procedure 0: NULL - No Operation
SYNOPSIS SYNOPSIS
<null> <null>
ARGUMENT ARGUMENT
skipping to change at page 107, line 5 skipping to change at page 109, line 5
Standard NULL procedure. Void argument, void response. This Standard NULL procedure. Void argument, void response. This
procedure has no functionality associated with it. Because of this procedure has no functionality associated with it. Because of this
it is sometimes used to measure the overhead of processing a it is sometimes used to measure the overhead of processing a
service request. Therefore, the server should ensure that no service request. Therefore, the server should ensure that no
unnecessary work is done in servicing this procedure. unnecessary work is done in servicing this procedure.
ERRORS ERRORS
None. None.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2. Procedure 1: COMPOUND - Compound Operations 14.2. Procedure 1: COMPOUND - Compound Operations
SYNOPSIS SYNOPSIS
compoundargs -> compoundres compoundargs -> compoundres
ARGUMENT ARGUMENT
union nfs_argop4 switch (nfs_opnum4 argop) { union nfs_argop4 switch (nfs_opnum4 argop) {
skipping to change at page 108, line 5 skipping to change at page 110, line 5
the COMPOUND procedure as a wrapper. the COMPOUND procedure as a wrapper.
The COMPOUND procedure is used to combine individual operations The COMPOUND procedure is used to combine individual operations
into a single RPC request. The server interprets each of the into a single RPC request. The server interprets each of the
operations in turn. If an operation is executed by the server and operations in turn. If an operation is executed by the server and
the status of that operation is NFS4_OK, then the next operation in the status of that operation is NFS4_OK, then the next operation in
the COMPOUND procedure is executed. The server continues this the COMPOUND procedure is executed. The server continues this
process until there are no more operations to be executed or one of process until there are no more operations to be executed or one of
the operations has a status value other than NFS4_OK. the operations has a status value other than NFS4_OK.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
In the processing of the COMPOUND procedure, the server may find In the processing of the COMPOUND procedure, the server may find
that it does not have the available resources to execute any or all that it does not have the available resources to execute any or all
of the operations within the COMPOUND sequence. In this case, the of the operations within the COMPOUND sequence. In this case, the
error NFS4ERR_RESOURCE will be returned for the particular error NFS4ERR_RESOURCE will be returned for the particular
operation within the COMPOUND procedure where the resource operation within the COMPOUND procedure where the resource
exhaustion occurred. This assumes that all previous operations exhaustion occurred. This assumes that all previous operations
within the COMPOUND sequence have been evaluated successfully. The within the COMPOUND sequence have been evaluated successfully. The
results for all of the evaluated operations must be returned to the results for all of the evaluated operations must be returned to the
client. client.
skipping to change at page 109, line 5 skipping to change at page 111, line 5
returned. If an operation array contains an operation 2 and the returned. If an operation array contains an operation 2 and the
minorversion field is non-zero and the server does not support the minorversion field is non-zero and the server does not support the
minor version, the server returns an error of minor version, the server returns an error of
NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the
NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other
errors. errors.
It is possible that the server receives a request that contains an It is possible that the server receives a request that contains an
operation that is beyond the last defined operation (e.g. operation that is beyond the last defined operation (e.g.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
OP_WRITE). In this case, the server obviously will fail the OP_WRITE). In this case, the server obviously will fail the
unknown operation. If this occurs, the server will return an unknown operation. If this occurs, the server will return an
operation "opcode" that is 1 greater than the largest defined operation "opcode" that is 1 greater than the largest defined
operation. For example, the server would return an opcode of operation. For example, the server would return an opcode of
OP_WRITE + 1. The server would then return a status of OP_WRITE + 1. The server would then return a status of
NFS4ERR_NOTSUPP to indicate an operation that is not defined and NFS4ERR_NOTSUPP to indicate an operation that is not defined and
therefore not supported. therefore not supported.
IMPLEMENTATION The definition of the "tag" in the request is left to the
implementor. It may be used to summarize the content of the
compound request for the benefit of packet sniffers and engineers
debugging implementations. However, the value of "tag" in the
response MUST be the same value as provided in the request.
Note that the definition of the "tag" in both the request and IMPLEMENTATION
response are left to the implementor. It may be used to summarize
the content of the compound request for the benefit of packet
sniffers and engineers debugging implementations.
Since an error of any type may occur after only a portion of the Since an error of any type may occur after only a portion of the
operations have been evaluated, the client must be prepared to operations have been evaluated, the client must be prepared to
recover from any failure. If the source of an NFS4ERR_RESOURCE recover from any failure. If the source of an NFS4ERR_RESOURCE
error was a complex or lengthy set of operations, it is likely that error was a complex or lengthy set of operations, it is likely that
if the number of operations were reduced the server would be able if the number of operations were reduced the server would be able
to evaluate them successfully. Therefore, the client is to evaluate them successfully. Therefore, the client is
responsible for dealing with this type of complexity in recovery. responsible for dealing with this type of complexity in recovery.
ERRORS ERRORS
All errors defined in the protocol All errors defined in the protocol
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.1. Operation 3: ACCESS - Check Access Rights 14.2.1. Operation 3: ACCESS - Check Access Rights
SYNOPSIS SYNOPSIS
(cfh), accessreq -> supported, accessrights (cfh), accessreq -> supported, accessrights
ARGUMENT ARGUMENT
const ACCESS4_READ = 0x00000001; const ACCESS4_READ = 0x00000001;
skipping to change at page 111, line 5 skipping to change at page 113, line 5
system object specified by the current filehandle. The client system object specified by the current filehandle. The client
encodes the set of access rights that are to be checked in the bit encodes the set of access rights that are to be checked in the bit
mask "access". The server checks the permissions encoded in the mask "access". The server checks the permissions encoded in the
bit mask. If a status of NFS4_OK is returned, two bit masks are bit mask. If a status of NFS4_OK is returned, two bit masks are
included in the response. The first, "supported", represents the included in the response. The first, "supported", represents the
access rights for which the server can verify reliably. The access rights for which the server can verify reliably. The
second, "access", represents the access rights available to the second, "access", represents the access rights available to the
user for the filehandle provided. On success, the current user for the filehandle provided. On success, the current
filehandle retains its value. filehandle retains its value.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
Note that the supported field will contain only as many values as Note that the supported field will contain only as many values as
was originally sent in the arguments. For example, if the client was originally sent in the arguments. For example, if the client
sends an ACCESS operation with only the ACCESS4_READ value set and sends an ACCESS operation with only the ACCESS4_READ value set and
the server supports this value, the server will return only the server supports this value, the server will return only
ACCESS4_READ even if it could have reliably checked other values. ACCESS4_READ even if it could have reliably checked other values.
The results of this operation are necessarily advisory in nature. The results of this operation are necessarily advisory in nature.
A return status of NFS4_OK and the appropriate bit set in the bit A 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 mask does not imply that such access will be allowed to the file
skipping to change at page 112, line 5 skipping to change at page 114, line 5
the same ID space as the client. In these cases (and perhaps the same ID space as the client. In these cases (and perhaps
others), the client can not reliably perform an access check with others), the client can not reliably perform an access check with
only current file attributes. only current file attributes.
In the NFS version 2 protocol, the only reliable way to determine In the NFS version 2 protocol, the only reliable way to determine
whether an operation was allowed was to try it and see if it whether an operation was allowed was to try it and see if it
succeeded or failed. Using the ACCESS procedure in the NFS version succeeded or failed. Using the ACCESS procedure in the NFS version
4 protocol, the client can ask the server to indicate whether or 4 protocol, the client can ask the server to indicate whether or
not one or more classes of operations are permitted. The ACCESS not one or more classes of operations are permitted. The ACCESS
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
operation is provided to allow clients to check before doing a operation is provided to allow clients to check before doing a
series of operations which will result in an access failure. The series of operations which will result in an access failure. The
OPEN operation provides a point where the server can verify access OPEN operation provides a point where the server can verify access
to the file object and method to return that information to the to the file object and method to return that information to the
client. The ACCESS operation is still useful for directory client. The ACCESS operation is still useful for directory
operations or for use in the case the UNIX API "access" is used on operations or for use in the case the UNIX API "access" is used on
the client. the client.
The information returned by the server in response to an ACCESS The information returned by the server in response to an ACCESS
skipping to change at page 112, line 39 skipping to change at page 114, line 39
determined by the access permissions on the directory in which the determined by the access permissions on the directory in which the
file resides, instead of being determined by the permissions of the file resides, instead of being determined by the permissions of the
file itself. Therefore, the mask returned enumerating which access file itself. Therefore, the mask returned enumerating which access
rights can be determined will have the ACCESS4_DELETE value set to rights can be determined will have the ACCESS4_DELETE value set to
0. This indicates to the client that the server was unable to 0. This indicates to the client that the server was unable to
check that particular access right. The ACCESS4_DELETE bit in the check that particular access right. The ACCESS4_DELETE bit in the
access mask returned will then be ignored by the client. access mask returned will then be ignored by the client.
ERRORS ERRORS
NFS4ERR_ACCES NFS4ERR_ACCESS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_DELAY NFS4ERR_DELAY
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_IO NFS4ERR_IO
NFS4ERR_MOVED NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE NFS4ERR_NOFILEHANDLE
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_WRONGSEC NFS4ERR_WRONGSEC
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.2. Operation 4: CLOSE - Close File 14.2.2. Operation 4: CLOSE - Close File
SYNOPSIS SYNOPSIS
(cfh), seqid, stateid -> stateid (cfh), seqid, open_stateid -> open_stateid
ARGUMENT ARGUMENT
struct CLOSE4args { struct CLOSE4args {
/* CURRENT_FH: object */ /* CURRENT_FH: object */
seqid4 seqid seqid4 seqid
stateid4 stateid; stateid4 open_stateid;
}; };
RESULT RESULT
union CLOSE4res switch (nfsstat4 status) { union CLOSE4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
stateid4 stateid; stateid4 open_stateid;
default: default:
void; void;
}; };
DESCRIPTION DESCRIPTION
The CLOSE operation releases share reservations for the file as The CLOSE operation releases share reservations for the regular or
specified by the current filehandle. The share reservations and named attribute file as specified by the current filehandle. The
other state information released at the server as a result of this share reservations and other state information released at the
CLOSE is only associated with the supplied stateid. The sequence server as a result of this CLOSE is only associated with the
id provides for the correct ordering. State associated with other supplied stateid. The sequence id provides for the correct
OPENs is not affected. ordering. State associated with other OPENs is not affected.
If record locks are held, the client SHOULD release all locks If record locks are held, the client SHOULD release all locks
before issuing a CLOSE. The server MAY free all outstanding locks before issuing a CLOSE. The server MAY free all outstanding locks
on CLOSE but some servers may not support the CLOSE of a file that on CLOSE but some servers may not support the CLOSE of a file that
still has record locks held. The server MUST return failure if any still has record locks held. The server MUST return failure if any
locks would exist after the CLOSE. locks would exist after the CLOSE.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
IMPLEMENTATION IMPLEMENTATION
ERRORS Even though CLOSE returns a stateid, this stateid is not useful to
the client and should be treated as deprecated. CLOSE "shuts down"
the state associated with all OPENs for the file by a single
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
open_owner. As noted above, CLOSE will either release all file
locking state or return an error. Therefore, the stateid returned
by CLOSE is not useful for operations that follow.
ERRORS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BAD_SEQID NFS4ERR_BAD_SEQID
NFS4ERR_BAD_STATEID NFS4ERR_BAD_STATEID
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_DELAY NFS4ERR_DELAY
NFS4ERR_EXPIRED NFS4ERR_EXPIRED
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_GRACE NFS4ERR_GRACE
NFS4ERR_INVAL NFS4ERR_INVAL
skipping to change at page 115, line 5 skipping to change at page 117, line 5
NFS4ERR_LEASE_MOVED NFS4ERR_LEASE_MOVED
NFS4ERR_LOCKS_HELD NFS4ERR_LOCKS_HELD
NFS4ERR_MOVED NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE NFS4ERR_NOFILEHANDLE
NFS4ERR_OLD_STATEID NFS4ERR_OLD_STATEID
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_STALE_STATEID NFS4ERR_STALE_STATEID
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.3. Operation 5: COMMIT - Commit Cached Data 14.2.3. Operation 5: COMMIT - Commit Cached Data
SYNOPSIS SYNOPSIS
(cfh), offset, count -> verifier (cfh), offset, count -> verifier
ARGUMENT ARGUMENT
struct COMMIT4args { struct COMMIT4args {
skipping to change at page 116, line 5 skipping to change at page 118, line 5
The server returns a write verifier upon successful completion of The server returns a write verifier upon successful completion of
the COMMIT. The write verifier is used by the client to determine the COMMIT. The write verifier is used by the client to determine
if the server has restarted or rebooted between the initial if the server has restarted or rebooted between the initial
WRITE(s) and the COMMIT. The client does this by comparing the WRITE(s) and the COMMIT. The client does this by comparing the
write verifier returned from the initial writes and the verifier write verifier returned from the initial writes and the verifier
returned by the COMMIT procedure. The server must vary the value returned by the COMMIT procedure. The server must vary the value
of the write verifier at each server event or instantiation that of the write verifier at each server event or instantiation that
may lead to a loss of uncommitted data. Most commonly this occurs may lead to a loss of uncommitted data. Most commonly this occurs
when the server is rebooted; however, other events at the server when the server is rebooted; however, other events at the server
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
may result in uncommitted data loss as well. may result in uncommitted data loss as well.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
IMPLEMENTATION IMPLEMENTATION
The COMMIT procedure is similar in operation and semantics to the The COMMIT procedure is similar in operation and semantics to the
POSIX fsync(2) system call that synchronizes a file's state with POSIX fsync(2) system call that synchronizes a file's state with
the disk (file data and metadata is flushed to disk or stable the disk (file data and metadata is flushed to disk or stable
skipping to change at page 117, line 5 skipping to change at page 119, line 5
close. In this case, the client would gather all of the buffers close. In this case, the client would gather all of the buffers
for this file that contain uncommitted data, do the COMMIT for this file that contain uncommitted data, do the COMMIT
operation with an offset of 0 and count of 0, and then free all of operation with an offset of 0 and count of 0, and then free all of
those buffers. Any other dirty buffers would be sent to the server those buffers. Any other dirty buffers would be sent to the server
in the normal fashion. in the normal fashion.
After a buffer is written by the client with the stable parameter After a buffer is written by the client with the stable parameter
set to UNSTABLE4, the buffer must be considered as modified by the set to UNSTABLE4, the buffer must be considered as modified by the
client until the buffer has either been flushed via a COMMIT client until the buffer has either been flushed via a COMMIT
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
operation or written via a WRITE operation with stable parameter operation or written via a WRITE operation with stable parameter
set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer set to FILE_SYNC4 or DATA_SYNC4. This is done to prevent the buffer
from being freed and reused before the data can be flushed to from being freed and reused before the data can be flushed to
stable storage on the server. stable storage on the server.
When a response is returned from either a WRITE or a COMMIT When a response is returned from either a WRITE or a COMMIT
operation and it contains a write verifier that is different than operation and it contains a write verifier that is different than
previously returned by the server, the client will need to previously returned by the server, the client will need to
retransmit all of the buffers containing uncommitted cached data to retransmit all of the buffers containing uncommitted cached data to
skipping to change at page 117, line 32 skipping to change at page 119, line 32
COMMIT operation to flush all of the data on the server to stable COMMIT operation to flush all of the data on the server to stable
storage. The timing of these retransmissions is left to the storage. The timing of these retransmissions is left to the
implementor. implementor.
The above description applies to page-cache-based systems as well The above description applies to page-cache-based systems as well
as buffer-cache-based systems. In those systems, the virtual as buffer-cache-based systems. In those systems, the virtual
memory system will need to be modified instead of the buffer cache. memory system will need to be modified instead of the buffer cache.
ERRORS ERRORS
NFS4ERR_ACCES NFS4ERR_ACCESS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_INVAL
NFS4ERR_IO NFS4ERR_IO
NFS4ERR_ISDIR NFS4ERR_ISDIR
NFS4ERR_LOCKED
NFS4ERR_MOVED NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE NFS4ERR_NOFILEHANDLE
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_ROFS NFS4ERR_ROFS
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_WRONGSEC NFS4ERR_WRONGSEC
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.4. Operation 6: CREATE - Create a Non-Regular File Object 14.2.4. Operation 6: CREATE - Create a Non-Regular File Object
SYNOPSIS SYNOPSIS
(cfh), name, type -> (cfh), change_info (cfh), name, type, attrs -> (cfh), change_info, attrs_set
ARGUMENT ARGUMENT
union createtype4 switch (nfs_ftype4 type) { union createtype4 switch (nfs_ftype4 type) {
case NF4LNK: case NF4LNK:
linktext4 linkdata; linktext4 linkdata;
case NF4BLK: case NF4BLK:
case NF4CHR: case NF4CHR:
specdata4 devdata; specdata4 devdata;
case NF4SOCK: case NF4SOCK:
case NF4FIFO: case NF4FIFO:
case NF4DIR: case NF4DIR:
void; void;
}; };
struct CREATE4args { struct CREATE4args {
/* CURRENT_FH: directory for creation */ /* CURRENT_FH: directory for creation */
component4 objname; component4 objname;
createtype4 objtype; createtype4 objtype;
fattr4 createattrs;
}; };
RESULT RESULT
struct CREATE4resok { struct CREATE4resok {
change_info4 cinfo; change_info4 cinfo;
bitmap4 attrset; /* attributes set */
}; };
union CREATE4res switch (nfsstat4 status) { union CREATE4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
CREATE4resok resok4; CREATE4resok resok4;
default: default:
void; void;
}; };
DESCRIPTION DESCRIPTION
The CREATE operation creates a non-regular file object in a The CREATE operation creates a non-regular file object in a
directory with a given name. The OPEN procedure MUST be used to directory with a given name. The OPEN procedure MUST be used to
create a regular file. create a regular file.
The objname specifies the name for the new object. If the objname The objname specifies the name for the new object. The objtype
has a length of 0 (zero), the error NFS4ERR_INVAL will be returned. determines the type of object to be created: directory, symlink,
The objtype determines the type of object to be created: directory,
symlink, etc.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
etc.
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.
For the directory where the new file object was created, the server For the directory where the new file object was created, the server
returns change_info4 information in cinfo. With the atomic field returns change_info4 information in cinfo. With the atomic field
of the change_info4 struct, the server will indicate if the before of the change_info4 struct, the server will indicate if the before
and after change attributes were obtained atomically with respect and after change attributes were obtained atomically with respect
to the file object creation. to the file object creation.
If the objname has a length of 0 (zero), or if objname does not If the objname has a length of 0 (zero), or if objname does not
obey the UTF-8 definition, the error NFS4ERR_INVAL will be obey the UTF-8 definition, the error NFS4ERR_INVAL will be
returned. returned.
The current filehandle is replaced by that of the new object. The current filehandle is replaced by that of the new object.
The createattrs specifies the initial set of attributes for the
object. The set of attributes may include any writable attribute
valid for the object type. When the operation is successful, the
server will return to the client an attribute mask signifying which
attributes were successfully set for the object.
IMPLEMENTATION IMPLEMENTATION
If the client desires to set attribute values after the create, a If the client desires to set attribute values after the create, a
SETATTR operation can be added to the COMPOUND request so that the SETATTR operation can be added to the COMPOUND request so that the
appropriate attributes will be set. appropriate attributes will be set.
It may be that the server's implementation places special meaning
on the names "." and ".." where they refer to special directories.
If this is the case and the client requests to CREATE a directory
(or other object) with these names, the server may return
NFS4ERR_INVAL. However, if the server does not place special
meaning on these names and a file object already exists with a
matching name, the server may return NFS4ERR_EXIST.
ERRORS ERRORS
NFS4ERR_ACCES NFS4ERR_ACCESS
NFS4ERR_ATTRNOTSUPP NFS4ERR_ATTRNOTSUPP
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BADTYPE NFS4ERR_BADTYPE
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_DQUOT NFS4ERR_DQUOT
NFS4ERR_EXIST NFS4ERR_EXIST
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_INVAL NFS4ERR_INVAL
NFS4ERR_IO NFS4ERR_IO
NFS4ERR_MOVED NFS4ERR_MOVED
Draft Specification NFS version 4 Protocol July 2002
NFS4ERR_NAMETOOLONG NFS4ERR_NAMETOOLONG
NFS4ERR_NOFILEHANDLE NFS4ERR_NOFILEHANDLE
NFS4ERR_NOSPC NFS4ERR_NOSPC
NFS4ERR_NOTDIR NFS4ERR_NOTDIR
NFS4ERR_NOTSUPP NFS4ERR_NOTSUPP
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_ROFS NFS4ERR_ROFS
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_WRONGSEC NFS4ERR_WRONGSEC
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery 14.2.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery
SYNOPSIS SYNOPSIS
clientid -> clientid ->
ARGUMENT ARGUMENT
struct DELEGPURGE4args { struct DELEGPURGE4args {
skipping to change at page 121, line 5 skipping to change at page 124, line 5
it received the results and committed them to the client's stable it received the results and committed them to the client's stable
storage. storage.
ERRORS ERRORS
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE_CLIENTID NFS4ERR_STALE_CLIENTID
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.6. Operation 8: DELEGRETURN - Return Delegation 14.2.6. Operation 8: DELEGRETURN - Return Delegation
SYNOPSIS SYNOPSIS
stateid -> (cfh), stateid ->
ARGUMENT ARGUMENT
struct DELEGRETURN4args { struct DELEGRETURN4args {
/* CURRENT_FH: delegated file */
stateid4 stateid; stateid4 stateid;
}; };
RESULT RESULT
struct DELEGRETURN4res { struct DELEGRETURN4res {
nfsstat4 status; nfsstat4 status;
}; };
DESCRIPTION DESCRIPTION
Returns the delegation represented by the given stateid. Returns the delegation represented by the current filehandle and
stateid.
ERRORS ERRORS
NFS4ERR_BAD_STATEID NFS4ERR_BAD_STATEID
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_EXPIRED
NFS4ERR_OLD_STATEID NFS4ERR_OLD_STATEID
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE_STATEID NFS4ERR_STALE_STATEID
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.7. Operation 9: GETATTR - Get Attributes 14.2.7. Operation 9: GETATTR - Get Attributes
SYNOPSIS SYNOPSIS
(cfh), attrbits -> attrbits, attrvals (cfh), attrbits -> attrbits, attrvals
ARGUMENT ARGUMENT
struct GETATTR4args { struct GETATTR4args {
skipping to change at page 123, line 5 skipping to change at page 126, line 5
value then it must not return the attribute value and must not set value then it must not return the attribute value and must not set
the attribute bit in the result bitmap. The server must return an the attribute bit in the result bitmap. The server must return an
error if it supports an attribute but cannot obtain its value. In error if it supports an attribute but cannot obtain its value. In
that case no attribute values will be returned. that case no attribute values will be returned.
All servers must support the mandatory attributes as specified in All servers must support the mandatory attributes as specified in
the section "File Attributes". the section "File Attributes".
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
IMPLEMENTATION IMPLEMENTATION
ERRORS ERRORS
NFS4ERR_ACCES NFS4ERR_ACCESS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_DELAY NFS4ERR_DELAY
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_INVAL NFS4ERR_INVAL
NFS4ERR_IO NFS4ERR_IO
NFS4ERR_MOVED NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE NFS4ERR_NOFILEHANDLE
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_WRONGSEC NFS4ERR_WRONGSEC
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.8. Operation 10: GETFH - Get Current Filehandle 14.2.8. Operation 10: GETFH - Get Current Filehandle
SYNOPSIS SYNOPSIS
(cfh) -> filehandle (cfh) -> filehandle
ARGUMENT ARGUMENT
/* CURRENT_FH: */ /* CURRENT_FH: */
skipping to change at page 125, line 5 skipping to change at page 128, line 5
PUTFH (directory filehandle) PUTFH (directory filehandle)
LOOKUP (entry name) LOOKUP (entry name)
GETFH GETFH
ERRORS ERRORS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_MOVED NFS4ERR_MOVED
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
NFS4ERR_NOFILEHANDLE NFS4ERR_NOFILEHANDLE
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_WRONGSEC NFS4ERR_WRONGSEC
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.9. Operation 11: LINK - Create Link to a File 14.2.9. Operation 11: LINK - Create Link to a File
SYNOPSIS SYNOPSIS
(sfh), (cfh), newname -> (cfh), change_info (sfh), (cfh), newname -> (cfh), change_info
ARGUMENT ARGUMENT
struct LINK4args { struct LINK4args {
skipping to change at page 126, line 41 skipping to change at page 129, line 41
void; void;
}; };
DESCRIPTION DESCRIPTION
The LINK operation creates an additional newname for the file The LINK operation creates an additional newname for the file
represented by the saved filehandle, as set by the SAVEFH represented by the saved filehandle, as set by the SAVEFH
operation, in the directory represented by the current filehandle. operation, in the directory represented by the current filehandle.
The existing file and the target directory must reside within the The existing file and the target directory must reside within the
same file system on the server. On success, the current filehandle same file system on the server. On success, the current filehandle
will continue to be the target directory. will continue to be the target directory. If an object exists in
the target directory with the same name as newname, the server must
return NFS4ERR_EXIST.
For the target directory, the server returns change_info4 For the target directory, the server returns change_info4
information in cinfo. With the atomic field of the change_info4 information in cinfo. With the atomic field of the change_info4
struct, the server will indicate if the before and after change struct, the server will indicate if the before and after change
attributes were obtained atomically with respect to the link attributes were obtained atomically with respect to the link
creation. creation.
If the newname has a length of 0 (zero), or if newname does not If the newname has a length of 0 (zero), or if newname does not
obey the UTF-8 definition, the error NFS4ERR_INVAL will be obey the UTF-8 definition, the error NFS4ERR_INVAL will be
returned. returned.
IMPLEMENTATION Draft Specification NFS version 4 Protocol July 2002
Draft Specification NFS version 4 Protocol November 2001 IMPLEMENTATION
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 attributes for the file should have a value for numlinks that is
one greater than the value before the LINK operation. one greater than the value before the LINK operation.
The comments under RENAME regarding object and target residing on The statement "file and the target directory must reside within the
the same file system apply here as well. The comments regarding the same file system on the server" means that the fsid fields in the
target name applies as well. attributes for the objects are the same. If they reside on
different file systems, the error, NFS4ERR_XDEV, is returned. On
some servers, the filenames, "." and "..", are illegal as newname.
In the case that newname is already linked to the file represented
by the saved filehandle, the server will return NFS4ERR_EXIST.
Note that symbolic links are created with the CREATE operation. Note that symbolic links are created with the CREATE operation.
ERRORS ERRORS
NFS4ERR_ACCES NFS4ERR_ACCESS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_DELAY NFS4ERR_DELAY
NFS4ERR_DQUOT NFS4ERR_DQUOT
NFS4ERR_EXIST NFS4ERR_EXIST
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_INVAL NFS4ERR_INVAL
NFS4ERR_IO NFS4ERR_IO
NFS4ERR_ISDIR NFS4ERR_ISDIR
NFS4ERR_MLINK NFS4ERR_MLINK
NFS4ERR_MOVED NFS4ERR_MOVED
NFS4ERR_NAMETOOLONG NFS4ERR_NAMETOOLONG
NFS4ERR_NOENT
NFS4ERR_NOFILEHANDLE NFS4ERR_NOFILEHANDLE
NFS4ERR_NOSPC NFS4ERR_NOSPC
NFS4ERR_NOTDIR NFS4ERR_NOTDIR
NFS4ERR_NOTSUPP NFS4ERR_NOTSUPP
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_ROFS NFS4ERR_ROFS
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_WRONGSEC NFS4ERR_WRONGSEC
NFS4ERR_XDEV NFS4ERR_XDEV
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.10. Operation 12: LOCK - Create Lock 14.2.10. Operation 12: LOCK - Create Lock
SYNOPSIS SYNOPSIS
(cfh) type, seqid, reclaim, stateid, offset, length -> stateid, (cfh) locktype, reclaim, offset, length, locker -> stateid
access
ARGUMENT ARGUMENT
struct open_to_lock_owner4 {
seqid4 open_seqid;
stateid4 open_stateid;
seqid4 lock_seqid;
lock_owner4 lock_owner;
};
struct exist_lock_owner4 {
stateid4 lock_stateid;
seqid4 lock_seqid;
};
union locker4 switch (bool new_lock_owner) {
case TRUE:
open_to_lock_owner4 open_owner;
case FALSE:
exist_lock_owner4 lock_owner;
};
enum nfs4_lock_type { enum nfs4_lock_type {
READ_LT = 1, READ_LT = 1,
WRITE_LT = 2, WRITE_LT = 2,
READW_LT = 3, /* blocking read */ READW_LT = 3, /* blocking read */
WRITEW_LT = 4 /* blocking write */ WRITEW_LT = 4 /* blocking write */
}; };
struct LOCK4args { struct LOCK4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
nfs_lock_type4 locktype; nfs_lock_type4 locktype;
seqid4 seqid;
bool reclaim; bool reclaim;
stateid4 stateid;
offset4 offset; offset4 offset;
length4 length; length4 length;
locker4 locker;
}; };
RESULT RESULT
struct LOCK4denied { struct LOCK4denied {
nfs_lockowner4 owner;
offset4 offset; offset4 offset;
length4 length; length4 length;
nfs_lock_type4 locktype;
Draft Specification NFS version 4 Protocol July 2002
lock_owner4 owner;
};
struct LOCK4resok {
stateid4 lock_stateid;
}; };
union LOCK4res switch (nfsstat4 status) { union LOCK4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
stateid4 stateid; LOCK4resok resok4;
case NFS4ERR_DENIED: case NFS4ERR_DENIED:
LOCK4denied denied; LOCK4denied denied;
default: default:
void; void;
}; };
DESCRIPTION DESCRIPTION
The LOCK operation requests a record lock for the byte range The LOCK operation requests a record lock for the byte range
specified by the offset and length parameters. The lock type is specified by the offset and length parameters. The lock type is
also specified to be one of the nfs4_lock_types. If this is a also specified to be one of the nfs4_lock_types. If this is a
Draft Specification NFS version 4 Protocol November 2001
reclaim request, the reclaim parameter will be TRUE; reclaim request, the reclaim parameter will be TRUE;
Bytes in a file may be locked even if those bytes are not currently Bytes in a file may be locked even if those bytes are not currently
allocated to the file. To lock the file from a specific offset allocated to the file. To lock the file from a specific offset
through the end-of-file (no matter how long the file actually is) through the end-of-file (no matter how long the file actually is)
use a length field with all bits set to 1 (one). To lock the use a length field with all bits set to 1 (one). To lock the
entire file, use an offset of 0 (zero) and a length with all bits entire file, use an offset of 0 (zero) and a length with all bits
set to 1. A length of 0 is reserved and should not be used. set to 1. A length of 0 is reserved and should not be used.
In the case that the lock is denied, the owner, offset, and length In the case that the lock is denied, the owner, offset, and length
skipping to change at page 129, line 31 skipping to change at page 132, line 52
IMPLEMENTATION IMPLEMENTATION
If the server is unable to determine the exact offset and length of If the server is unable to determine the exact offset and length of
the conflicting lock, the same offset and length that were provided the conflicting lock, the same offset and length that were provided
in the arguments should be returned in the denied results. The in the arguments should be returned in the denied results. The
File Locking section contains a full description of this and the File Locking section contains a full description of this and the
other file locking operations. other file locking operations.
ERRORS ERRORS
NFS4ERR_ACCES NFS4ERR_ACCESS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BAD_SEQID NFS4ERR_BAD_SEQID
NFS4ERR_BAD_STATEID NFS4ERR_BAD_STATEID
Draft Specification NFS version 4 Protocol July 2002
NFS4ERR_BADXDR NFS4ERR_BADXDR
NFS4ERR_DELAY NFS4ERR_DELAY
NFS4ERR_DENIED NFS4ERR_DENIED
NFS4ERR_EXPIRED NFS4ERR_EXPIRED
NFS4ERR_FHEXPIRED NFS4ERR_FHEXPIRED
NFS4ERR_GRACE NFS4ERR_GRACE
NFS4ERR_INVAL NFS4ERR_INVAL
NFS4ERR_ISDIR NFS4ERR_ISDIR
NFS4ERR_LEASE_MOVED NFS4ERR_LEASE_MOVED
NFS4ERR_LOCK_RANGE NFS4ERR_LOCK_RANGE
skipping to change at page 130, line 5 skipping to change at page 134, line 5
NFS4ERR_OLD_STATEID NFS4ERR_OLD_STATEID
NFS4ERR_RECLAIM_BAD NFS4ERR_RECLAIM_BAD
NFS4ERR_RECLAIM_CONFLICT NFS4ERR_RECLAIM_CONFLICT
NFS4ERR_RESOURCE NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT NFS4ERR_SERVERFAULT
NFS4ERR_STALE NFS4ERR_STALE
NFS4ERR_STALE_CLIENTID NFS4ERR_STALE_CLIENTID
NFS4ERR_STALE_STATEID NFS4ERR_STALE_STATEID
NFS4ERR_WRONGSEC NFS4ERR_WRONGSEC
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
14.2.11. Operation 13: LOCKT - Test For Lock 14.2.11. Operation 13: LOCKT - Test For Lock
SYNOPSIS SYNOPSIS
(cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED -> (cfh) type, owner, offset, length -> {void, NFS4ERR_DENIED ->
owner} owner}
ARGUMENT ARGUMENT
skipping to change at page 131, line 5 skipping to change at page 135, line 5
If a conflicting lock exists, the owner, offset, length, and type If a conflicting lock exists, the owner, offset, length, and type
of the conflicting lock are returned; if no lock is held, nothing of the conflicting lock are returned; if no lock is held, nothing
other than NFS4_OK is returned. other than NFS4_OK is returned.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
IMPLEMENTATION IMPLEMENTATION
If the server is unable to determine the exact offset and length of If the server is unable to determine the exact offset and length of
Draft Specification NFS version 4 Protocol November 2001 Draft Specification NFS version 4 Protocol July 2002
the conflicting lock, the same offset and length that were provided the conflicting lock, the same offset and length that were provided
in the arguments should be returned in the denied results. The in the arguments should be returned in the denied results. The
File Locking section contains further discussion of the file File Locking section contains further discussion of the file
locking mechanisms. locking mechanisms.
LOCKT uses nfs_lockowner4 instead of a stateid4, as LOCK does, to LOCKT uses nfs_lockowner4 instead of a stateid4, as LOCK does, to
identify the owner so that the client does not have to open the identify the owner so that the client does not have to open the
file to test for the existence of a lock. file to test for the existence of a lock.
ERRORS ERRORS
NFS4ERR_ACCES NFS4ERR_ACCESS
NFS4ERR_BADHANDLE NFS4ERR_BADHANDLE
NFS4ERR_BADXDR NFS4ERR_BADXDR