draft-ietf-nfsv4-rfc3530bis-05.txt   draft-ietf-nfsv4-rfc3530bis-06.txt 
NFSv4 T. Haynes NFSv4 T. Haynes
Internet-Draft D. Noveck Internet-Draft D. Noveck
Intended status: Standards Track Editors Intended status: Standards Track Editors
Expires: April 24, 2011 October 21, 2010 Expires: August 20, 2011 February 16, 2011
NFS Version 4 Protocol NFS Version 4 Protocol
draft-ietf-nfsv4-rfc3530bis-05.txt draft-ietf-nfsv4-rfc3530bis-06.txt
Abstract Abstract
The Network File System (NFS) version 4 is a distributed filesystem The Network File System (NFS) version 4 is a distributed filesystem
protocol which owes heritage to NFS protocol version 2, RFC 1094, and protocol which owes heritage to NFS protocol version 2, RFC 1094, and
version 3, RFC 1813. Unlike earlier versions, the NFS version 4 version 3, RFC 1813. Unlike earlier versions, the NFS version 4
protocol supports traditional file access while integrating support protocol supports traditional file access while integrating support
for file locking and the mount protocol. In addition, support for for file locking and the mount protocol. In addition, support for
strong security (and its negotiation), compound operations, client strong security (and its negotiation), compound operations, client
caching, and internationalization have been added. Of course, caching, and internationalization have been added. Of course,
skipping to change at page 2, line 8 skipping to change at page 2, line 8
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 24, 2011. This Internet-Draft will expire on August 20, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 4, line 8 skipping to change at page 4, line 8
5.4. Classification of Attributes . . . . . . . . . . . . . . 39 5.4. Classification of Attributes . . . . . . . . . . . . . . 39
5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 40 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 40
5.6. REQUIRED Attributes - List and Definition References . . 40 5.6. REQUIRED Attributes - List and Definition References . . 40
5.7. RECOMMENDED Attributes - List and Definition 5.7. RECOMMENDED Attributes - List and Definition
References . . . . . . . . . . . . . . . . . . . . . . . 41 References . . . . . . . . . . . . . . . . . . . . . . . 41
5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 42 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 42
5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 42 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 42
5.8.2. Definitions of Uncategorized RECOMMENDED 5.8.2. Definitions of Uncategorized RECOMMENDED
Attributes . . . . . . . . . . . . . . . . . . . . . 44 Attributes . . . . . . . . . . . . . . . . . . . . . 44
5.9. Interpreting owner and owner_group . . . . . . . . . . . 50 5.9. Interpreting owner and owner_group . . . . . . . . . . . 50
5.10. Character Case Attributes . . . . . . . . . . . . . . . 52 5.10. Character Case Attributes . . . . . . . . . . . . . . . 53
6. Access Control Attributes . . . . . . . . . . . . . . . . . . 53 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 53
6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 53 6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.2. File Attributes Discussion . . . . . . . . . . . . . . . 54 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 54
6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 54 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 54
6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 68 6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 68
6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 68 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 69
6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 68 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 69
6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 69 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 70
6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 70 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 71
6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 71 6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 71
6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 72 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 72
6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 72 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 73
7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 74 7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 74
7.1. Location Attributes . . . . . . . . . . . . . . . . . . 74 7.1. Location Attributes . . . . . . . . . . . . . . . . . . 75
7.2. File System Presence or Absence . . . . . . . . . . . . 75 7.2. File System Presence or Absence . . . . . . . . . . . . 75
7.3. Getting Attributes for an Absent File System . . . . . . 76 7.3. Getting Attributes for an Absent File System . . . . . . 76
7.3.1. GETATTR Within an Absent File System . . . . . . . . 76 7.3.1. GETATTR Within an Absent File System . . . . . . . . 76
7.3.2. READDIR and Absent File Systems . . . . . . . . . . 77 7.3.2. READDIR and Absent File Systems . . . . . . . . . . 77
7.4. Uses of Location Information . . . . . . . . . . . . . . 77 7.4. Uses of Location Information . . . . . . . . . . . . . . 78
7.4.1. File System Replication . . . . . . . . . . . . . . 78 7.4.1. File System Replication . . . . . . . . . . . . . . 79
7.4.2. File System Migration . . . . . . . . . . . . . . . 79 7.4.2. File System Migration . . . . . . . . . . . . . . . 79
7.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 80 7.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 80
7.5. Location Entries and Server Identity . . . . . . . . . . 80 7.5. Location Entries and Server Identity . . . . . . . . . . 81
7.6. Additional Client-Side Considerations . . . . . . . . . 81 7.6. Additional Client-Side Considerations . . . . . . . . . 81
7.7. Effecting File System Transitions . . . . . . . . . . . 82 7.7. Effecting File System Transitions . . . . . . . . . . . 82
7.7.1. File System Transitions and Simultaneous Access . . 83 7.7.1. File System Transitions and Simultaneous Access . . 84
7.7.2. Filehandles and File System Transitions . . . . . . 83 7.7.2. Filehandles and File System Transitions . . . . . . 84
7.7.3. Fileids and File System Transitions . . . . . . . . 84 7.7.3. Fileids and File System Transitions . . . . . . . . 84
7.7.4. Fsids and File System Transitions . . . . . . . . . 85 7.7.4. Fsids and File System Transitions . . . . . . . . . 86
7.7.5. The Change Attribute and File System Transitions . . 85 7.7.5. The Change Attribute and File System Transitions . . 86
7.7.6. Lock State and File System Transitions . . . . . . . 86 7.7.6. Lock State and File System Transitions . . . . . . . 86
7.7.7. Write Verifiers and File System Transitions . . . . 88 7.7.7. Write Verifiers and File System Transitions . . . . 88
7.7.8. Readdir Cookies and Verifiers and File System 7.7.8. Readdir Cookies and Verifiers and File System
Transitions . . . . . . . . . . . . . . . . . . . . 88 Transitions . . . . . . . . . . . . . . . . . . . . 89
7.7.9. File System Data and File System Transitions . . . . 89 7.7.9. File System Data and File System Transitions . . . . 89
7.8. Effecting File System Referrals . . . . . . . . . . . . 90 7.8. Effecting File System Referrals . . . . . . . . . . . . 90
7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 90 7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 91
7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 94 7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 94
7.9. The Attribute fs_locations . . . . . . . . . . . . . . . 97 7.9. The Attribute fs_locations . . . . . . . . . . . . . . . 97
7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 98 7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 99
8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 100 8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 100
8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 100 8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 100
8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 100 8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 100
8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 100 8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 101
8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 101 8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 101
8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 101 8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 101
8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 101 8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 102
8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 102 8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 102
8.8. Security Policy and Name Space Presentation . . . . . . 102 8.8. Security Policy and Name Space Presentation . . . . . . 103
9. File Locking and Share Reservations . . . . . . . . . . . . . 103 9. File Locking and Share Reservations . . . . . . . . . . . . . 103
9.1. Locking . . . . . . . . . . . . . . . . . . . . . . . . 104 9.1. Locking . . . . . . . . . . . . . . . . . . . . . . . . 104
9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 104 9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 104
9.1.2. Server Release of Clientid . . . . . . . . . . . . . 107 9.1.2. Server Release of Clientid . . . . . . . . . . . . . 107
9.1.3. lock_owner and stateid Definition . . . . . . . . . 108 9.1.3. lock_owner and stateid Definition . . . . . . . . . 108
9.1.4. Use of the stateid and Locking . . . . . . . . . . . 109 9.1.4. Use of the stateid and Locking . . . . . . . . . . . 109
9.1.5. Sequencing of Lock Requests . . . . . . . . . . . . 111 9.1.5. Sequencing of Lock Requests . . . . . . . . . . . . 112
9.1.6. Recovery from Replayed Requests . . . . . . . . . . 112 9.1.6. Recovery from Replayed Requests . . . . . . . . . . 113
9.1.7. Releasing lock_owner State . . . . . . . . . . . . . 113 9.1.7. Releasing lock_owner State . . . . . . . . . . . . . 113
9.1.8. Use of Open Confirmation . . . . . . . . . . . . . . 113 9.1.8. Use of Open Confirmation . . . . . . . . . . . . . . 113
9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 114 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 114
9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 115 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 115
9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 115 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 115
9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 116 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 116
9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 116 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 117
9.6.1. Client Failure and Recovery . . . . . . . . . . . . 117 9.6.1. Client Failure and Recovery . . . . . . . . . . . . 117
9.6.2. Server Failure and Recovery . . . . . . . . . . . . 117 9.6.2. Server Failure and Recovery . . . . . . . . . . . . 118
9.6.3. Network Partitions and Recovery . . . . . . . . . . 119 9.6.3. Network Partitions and Recovery . . . . . . . . . . 120
9.7. Recovery from a Lock Request Timeout or Abort . . . . . 123 9.7. Recovery from a Lock Request Timeout or Abort . . . . . 123
9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 123 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 124
9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 124 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 125
9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 125 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 126
9.10.1. Close and Retention of State Information . . . . . . 126 9.10.1. Close and Retention of State Information . . . . . . 126
9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 126 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 127
9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 127 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 128
9.13. Clocks, Propagation Delay, and Calculating Lease 9.13. Clocks, Propagation Delay, and Calculating Lease
Expiration . . . . . . . . . . . . . . . . . . . . . . . 127 Expiration . . . . . . . . . . . . . . . . . . . . . . . 128
9.14. Migration, Replication and State . . . . . . . . . . . . 128 9.14. Migration, Replication and State . . . . . . . . . . . . 129
9.14.1. Migration and State . . . . . . . . . . . . . . . . 128 9.14.1. Migration and State . . . . . . . . . . . . . . . . 129
9.14.2. Replication and State . . . . . . . . . . . . . . . 129 9.14.2. Replication and State . . . . . . . . . . . . . . . 130
9.14.3. Notification of Migrated Lease . . . . . . . . . . . 130 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 130
9.14.4. Migration and the Lease_time Attribute . . . . . . . 130 9.14.4. Migration and the Lease_time Attribute . . . . . . . 131
10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 131 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 131
10.1. Performance Challenges for Client-Side Caching . . . . . 131 10.1. Performance Challenges for Client-Side Caching . . . . . 132
10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 132 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 133
10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 134 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 134
10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 136 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 136
10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 136 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 137
10.3.2. Data Caching and File Locking . . . . . . . . . . . 137 10.3.2. Data Caching and File Locking . . . . . . . . . . . 138
10.3.3. Data Caching and Mandatory File Locking . . . . . . 139 10.3.3. Data Caching and Mandatory File Locking . . . . . . 139
10.3.4. Data Caching and File Identity . . . . . . . . . . . 139 10.3.4. Data Caching and File Identity . . . . . . . . . . . 140
10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 140 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 141
10.4.1. Open Delegation and Data Caching . . . . . . . . . . 142 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 143
10.4.2. Open Delegation and File Locks . . . . . . . . . . . 144 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 144
10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 144 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 145
10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 147 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 148
10.4.5. Clients that Fail to Honor Delegation Recalls . . . 149 10.4.5. Clients that Fail to Honor Delegation Recalls . . . 149
10.4.6. Delegation Revocation . . . . . . . . . . . . . . . 150 10.4.6. Delegation Revocation . . . . . . . . . . . . . . . 150
10.5. Data Caching and Revocation . . . . . . . . . . . . . . 150 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 151
10.5.1. Revocation Recovery for Write Open Delegation . . . 151 10.5.1. Revocation Recovery for Write Open Delegation . . . 151
10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 151 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 152
10.7. Data and Metadata Caching and Memory Mapped Files . . . 153 10.7. Data and Metadata Caching and Memory Mapped Files . . . 154
10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 156 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 156
10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 157 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 157
11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 157 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 158
12. Internationalization . . . . . . . . . . . . . . . . . . . . 160 12. Internationalization . . . . . . . . . . . . . . . . . . . . 161
12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 161 12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 162
12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 161 12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 162
12.1.2. Normalization, Equivalence, and Confusability . . . 162 12.1.2. Normalization, Equivalence, and Confusability . . . 163
12.2. String Type Overview . . . . . . . . . . . . . . . . . . 165 12.2. String Type Overview . . . . . . . . . . . . . . . . . . 165
12.2.1. Overall String Class Divisions . . . . . . . . . . . 165 12.2.1. Overall String Class Divisions . . . . . . . . . . . 166
12.2.2. Divisions by Typedef Parent types . . . . . . . . . 166 12.2.2. Divisions by Typedef Parent types . . . . . . . . . 167
12.2.3. Individual Types and Their Handling . . . . . . . . 167 12.2.3. Individual Types and Their Handling . . . . . . . . 167
12.3. Errors Related to Strings . . . . . . . . . . . . . . . 168 12.3. Errors Related to Strings . . . . . . . . . . . . . . . 169
12.4. Types with Pre-processing to Resolve Mixture Issues . . 169 12.4. Types with Pre-processing to Resolve Mixture Issues . . 170
12.4.1. Processing of Principal Strings . . . . . . . . . . 169 12.4.1. Processing of Principal Strings . . . . . . . . . . 170
12.4.2. Processing of Server Id Strings . . . . . . . . . . 169 12.4.2. Processing of Server Id Strings . . . . . . . . . . 170
12.5. String Types without Internationalization Processing . . 170 12.5. String Types without Internationalization Processing . . 171
12.6. Types with Processing Defined by Other Internet Areas . 170 12.6. Types with Processing Defined by Other Internet Areas . 171
12.7. String Types with NFS-specific Processing . . . . . . . 171 12.7. String Types with NFS-specific Processing . . . . . . . 172
12.7.1. Handling of File Name Components . . . . . . . . . . 172 12.7.1. Handling of File Name Components . . . . . . . . . . 173
12.7.2. Processing of Link Text . . . . . . . . . . . . . . 181 12.7.2. Processing of Link Text . . . . . . . . . . . . . . 182
12.7.3. Processing of Principal Prefixes . . . . . . . . . . 182 12.7.3. Processing of Principal Prefixes . . . . . . . . . . 183
13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 183 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 184
13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 183 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 184
13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 185 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 186
13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 186 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 187
13.1.3. Compound Structure Errors . . . . . . . . . . . . . 187 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 188
13.1.4. File System Errors . . . . . . . . . . . . . . . . . 188 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 189
13.1.5. State Management Errors . . . . . . . . . . . . . . 190 13.1.5. State Management Errors . . . . . . . . . . . . . . 191
13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 191 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 192
13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 191 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 192
13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 192 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 193
13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 193 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 194
13.1.10. Client Management Errors . . . . . . . . . . . . . . 194 13.1.10. Client Management Errors . . . . . . . . . . . . . . 195
13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 194 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 195
13.2. Operations and their valid errors . . . . . . . . . . . 195 13.2. Operations and their valid errors . . . . . . . . . . . 196
13.3. Callback operations and their valid errors . . . . . . . 203 13.3. Callback operations and their valid errors . . . . . . . 204
13.4. Errors and the operations that use them . . . . . . . . 203 13.4. Errors and the operations that use them . . . . . . . . 204
14. NFS version 4 Requests . . . . . . . . . . . . . . . . . . . 207 14. NFS version 4 Requests . . . . . . . . . . . . . . . . . . . 208
14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 208 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 209
14.2. Evaluation of a Compound Request . . . . . . . . . . . . 208 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 209
14.3. Synchronous Modifying Operations . . . . . . . . . . . . 209 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 210
14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 210 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 211
15. NFS version 4 Procedures . . . . . . . . . . . . . . . . . . 210 15. NFS version 4 Procedures . . . . . . . . . . . . . . . . . . 211
15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 210 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 211
15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 210 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 211
15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 213 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 214
15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 216 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 217
15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 217 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 218
15.6. Operation 6: CREATE - Create a Non-Regular File Object . 219 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 220
15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 222 Recovery . . . . . . . . . . . . . . . . . . . . . . . . 223
15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 223 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 224
15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 223 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 224
15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 224 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 225
15.11. Operation 11: LINK - Create Link to a File . . . . . . . 225 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 226
15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 227 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 228
15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 231 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 232
15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 232 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 233
15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 233 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 235
15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 235 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 236
15.17. Operation 17: NVERIFY - Verify Difference in 15.17. Operation 17: NVERIFY - Verify Difference in
Attributes . . . . . . . . . . . . . . . . . . . . . . . 236 Attributes . . . . . . . . . . . . . . . . . . . . . . . 237
15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 237 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 238
15.19. Operation 19: OPENATTR - Open Named Attribute 15.19. Operation 19: OPENATTR - Open Named Attribute
Directory . . . . . . . . . . . . . . . . . . . . . . . 246 Directory . . . . . . . . . . . . . . . . . . . . . . . 248
15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 247 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 249
15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 249 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 251
15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 251 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 252
15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 251 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 252
15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 253 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 254
15.25. Operation 25: READ - Read from File . . . . . . . . . . 253 15.25. Operation 25: READ - Read from File . . . . . . . . . . 254
15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 255 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 257
15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 259 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 260
15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 260 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 261
15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 262 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 263
15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 264 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 265
15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 265 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 266
15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 266 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 267
15.33. Operation 33: SECINFO - Obtain Available Security . . . 266 15.33. Operation 33: SECINFO - Obtain Available Security . . . 268
15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 269 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 271
15.35. Operation 35: SETCLIENTID - Negotiate Clientid . . . . . 272 15.35. Operation 35: SETCLIENTID - Negotiate Clientid . . . . . 274
15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid . . 275 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid . . 277
15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 279 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 281
15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 280 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 282
15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner
State . . . . . . . . . . . . . . . . . . . . . . . . . 284 State . . . . . . . . . . . . . . . . . . . . . . . . . 286
15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 285 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 287
16. NFS version 4 Callback Procedures . . . . . . . . . . . . . . 286 16. NFS version 4 Callback Procedures . . . . . . . . . . . . . . 288
16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 286 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 288
16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 287 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 289
16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 288 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 290
16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 289 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 291
16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback
Operation . . . . . . . . . . . . . . . . . . . . . 290 Operation . . . . . . . . . . . . . . . . . . . . . 292
17. Security Considerations . . . . . . . . . . . . . . . . . . . 291 17. Security Considerations . . . . . . . . . . . . . . . . . . . 293
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 293 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 295
18.1. Named Attribute Definition . . . . . . . . . . . . . . . 293 18.1. Named Attribute Definition . . . . . . . . . . . . . . . 295
18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 293 18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 295
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 294 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 296
19.1. Normative References . . . . . . . . . . . . . . . . . . 294 19.1. Normative References . . . . . . . . . . . . . . . . . . 296
19.2. Informative References . . . . . . . . . . . . . . . . . 295 19.2. Informative References . . . . . . . . . . . . . . . . . 297
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 297 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 299
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 297 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 299
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 297 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 300
1. Introduction 1. Introduction
1.1. Changes since RFC 3530 1.1. Changes since RFC 3530
This document, together with the companion XDR description document This document, together with the companion XDR description document
[2], obsoletes RFC 3530 [11] as the authoritative document describing [2], obsoletes RFC 3530 [11] as the authoritative document describing
NFSv4. It does not introduce any over-the-wire protocol changes, in NFSv4. It does not introduce any over-the-wire protocol changes, in
the sense that previously valid requests requests remain valid. the sense that previously valid requests requests remain valid.
However, some requests previously defined as invalid, although not However, some requests previously defined as invalid, although not
skipping to change at page 16, line 22 skipping to change at page 16, line 22
other client has the ability to write to the file for the duration of other client has the ability to write to the file for the duration of
the delegation. If the client is granted a write delegation, the the delegation. If the client is granted a write delegation, the
client is assured that no other client has read or write access to client is assured that no other client has read or write access to
the file. the file.
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 cannot 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, or WRITE without immediate
interaction with the server. interaction with the server.
1.6. General Definitions 1.6. 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 the resources. The client may be an application which contains the
logic to access the NFS server directly. The client may also be logic to access the NFS server directly. The client may also be
skipping to change at page 25, line 40 skipping to change at page 25, line 40
as a standards track RFC revises this requirement to use a different as a standards track RFC revises this requirement to use a different
IETF-approved congestion control transport protocol. IETF-approved congestion control transport protocol.
If TCP is used as the transport, the client and server SHOULD use If TCP is used as the transport, the client and server SHOULD use
persistent connections. This will prevent the weakening of TCP's persistent connections. This will prevent the weakening of TCP's
congestion control via short lived connections and will improve congestion control via short lived connections and will improve
performance for the WAN environment by eliminating the need for SYN performance for the WAN environment by eliminating the need for SYN
handshakes. handshakes.
As noted in Section 17, the authentication model for NFS version 4 As noted in Section 17, the authentication model for NFS version 4
has moved from machine-based to principal- based. However, this has moved from machine-based to principal-based. However, this
modification of the authentication model does not imply a technical modification of the authentication model does not imply a technical
requirement to move the TCP connection management model from whole requirement to move the TCP connection management model from whole
machine-based to one based on a per user model. In particular, NFS machine-based to one based on a per user model. In particular, NFS
over TCP client implementations have traditionally multiplexed over TCP client implementations have traditionally multiplexed
traffic for multiple users over a common TCP connection between an traffic for multiple users over a common TCP connection between an
NFS client and server. This has been true, regardless whether the NFS client and server. This has been true, regardless whether the
NFS client is using AUTH_SYS, AUTH_DH, RPCSEC_GSS or any other NFS client is using AUTH_SYS, AUTH_DH, RPCSEC_GSS or any other
flavor. Similarly, NFS over TCP server implementations have assumed flavor. Similarly, NFS over TCP server implementations have assumed
such a model and thus scale the implementation of TCP connection such a model and thus scale the implementation of TCP connection
management in proportion to the number of expected client machines. management in proportion to the number of expected client machines.
skipping to change at page 29, line 9 skipping to change at page 29, line 9
1 2 3 4 5 1 2 3 4 5
-------------------------------------------------------------------- --------------------------------------------------------------------
390009 spkm3 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_none 390009 spkm3 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_none
390010 spkm3i 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_integrity 390010 spkm3i 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_integrity
390011 spkm3p 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_privacy 390011 spkm3p 1.3.6.1.5.5.1.3 negotiated rpc_gss_svc_privacy
For a discussion as to why the mechanism algorithm is listed as For a discussion as to why the mechanism algorithm is listed as
"negotiated", see Section 3.2.1.2. "negotiated", see Section 3.2.1.2.
Because SPKM-3 negotiates the algorithms, subsequent calls to SPKM- Because SPKM-3 negotiates the algorithms, subsequent calls to
3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality of SPKM-3's GSS_Wrap() and GSS_GetMIC() by RPCSEC_GSS will use a quality
protection value of 0 (zero). See section 5.2 of [22] for an of protection value of 0 (zero). See section 5.2 of [22] for an
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.
skipping to change at page 35, line 15 skipping to change at page 35, line 15
particular filesystem. This attribute is a bitmask with the particular filesystem. This attribute is a bitmask with the
following values: following values:
FH4_PERSISTENT The value of FH4_PERSISTENT is used to indicate a FH4_PERSISTENT The value of FH4_PERSISTENT is used to indicate a
persistent filehandle, which is valid until the object is removed persistent filehandle, which is valid until the object is removed
from the filesystem. The server will not return NFS4ERR_FHEXPIRED from the filesystem. The server will not return NFS4ERR_FHEXPIRED
for this filehandle. FH4_PERSISTENT is defined as a value in for this filehandle. FH4_PERSISTENT is defined as a value in
which none of the bits specified below are set. which none of the bits specified below are set.
FH4_VOLATILE_ANY The filehandle may expire at any time, except as FH4_VOLATILE_ANY The filehandle may expire at any time, except as
specifically excluded (i.e., FH4_NO_EXPIRE_WITH_OPEN). specifically excluded (i.e., FH4_NOEXPIRE_WITH_OPEN).
FH4_NOEXPIRE_WITH_OPEN May only be set when FH4_VOLATILE_ANY is set. FH4_NOEXPIRE_WITH_OPEN May only be set when FH4_VOLATILE_ANY is set.
If this bit is set, then the meaning of FH4_VOLATILE_ANY is If this bit is set, then the meaning of FH4_VOLATILE_ANY is
qualified to exclude any expiration of the filehandle when it is qualified to exclude any expiration of the filehandle when it is
open. open.
FH4_VOL_MIGRATION The filehandle will expire as a result of FH4_VOL_MIGRATION The filehandle will expire as a result of
migration. If FH4_VOL_ANY is set, FH4_VOL_MIGRATION is redundant. migration. If FH4_VOLATILE_ANY is set, FH4_VOL_MIGRATION is
redundant.
FH4_VOL_RENAME The filehandle will expire during rename. This FH4_VOL_RENAME The filehandle will expire during rename. This
includes a rename by the requesting client or a rename by any includes a rename by the requesting client or a rename by any
other client. If FH4_VOL_ANY is set, FH4_VOL_RENAME is redundant. other client. If FH4_VOLATILE_ANY is set, FH4_VOL_RENAME is
redundant.
Servers which provide volatile filehandles that may expire while open Servers which provide volatile filehandles that may expire while open
(i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if (i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if
FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN not set), should FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN not set), should
deny a RENAME or REMOVE that would affect an OPEN file of any of the deny a RENAME or REMOVE that would affect an OPEN file of any of the
components leading to the OPEN file. In addition, the server should components leading to the OPEN file. In addition, the server should
deny all RENAME or REMOVE requests during the grace period upon deny all RENAME or REMOVE requests during the grace period upon
server restart. server restart.
Note that the bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the Note that the bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the
client to determine that expiration has occurred whenever a specific client to determine that expiration has occurred whenever a specific
event occurs, without an explicit filehandle expiration error from event occurs, without an explicit filehandle expiration error from
the server. FH4_VOL_ANY does not provide this form of information. the server. FH4_VOLATILE_ANY does not provide this form of
In situations where the server will expire many, but not all information. In situations where the server will expire many, but
filehandles upon migration (e.g., all but those that are open), not all filehandles upon migration (e.g., all but those that are
FH4_VOLATILE_ANY (in this case with FH4_NOEXPIRE_WITH_OPEN) is a open), FH4_VOLATILE_ANY (in this case with FH4_NOEXPIRE_WITH_OPEN) is
better choice since the client may not assume that all filehandles a better choice since the client may not assume that all filehandles
will expire when migration occurs, and it is likely that additional will expire when migration occurs, and it is likely that additional
expirations will occur (as a result of file CLOSE) that are separated expirations will occur (as a result of file CLOSE) that are separated
in time from the migration event itself. in time from the migration event itself.
4.2.4. One Method of Constructing a Volatile Filehandle 4.2.4. One Method of Constructing a Volatile Filehandle
A volatile filehandle, while opaque to the client could contain: A volatile filehandle, while opaque to the client could contain:
[volatile bit = 1 | server boot time | slot | generation number] [volatile bit = 1 | server boot time | slot | generation number]
skipping to change at page 37, line 20 skipping to change at page 37, line 20
LOOKUP B LOOKUP B
GETFH GETFH
Note that the COMPOUND procedure does not provide atomicity. This Note that the COMPOUND procedure does not provide atomicity. This
example only reduces the overhead of recovering from an expired example only reduces the overhead of recovering from an expired
filehandle. filehandle.
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 need to be
in a flexible manner. The NFSv3 fattr3 structure contains a fixed handled in a flexible manner. The NFSv3 fattr3 structure contains a
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 cannot 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 NFSv4.0 protocol, the client is able query what attributes the the NFSv4.0 protocol, the client is able to query what attributes the
server supports and construct requests with only those supported server supports and construct requests with only those supported
attributes (or a subset thereof). attributes (or a subset thereof).
To this end, attributes are divided into three groups: REQUIRED, To this end, attributes are divided into three groups: REQUIRED,
RECOMMENDED, and named. Both REQUIRED and RECOMMENDED attributes are RECOMMENDED, and named. Both REQUIRED and RECOMMENDED attributes are
supported in the NFSv4.0 protocol by a specific and well-defined supported in the NFSv4.0 protocol by a specific and well-defined
encoding and are identified by number. They are requested by setting encoding and are identified by number. They are requested by setting
a bit in the bit vector sent in the GETATTR request; the server a bit in the bit vector sent in the GETATTR request; the server
response includes a bit vector to list what attributes were returned response includes a bit vector to list what attributes were returned
in the response. New REQUIRED or RECOMMENDED attributes may be added in the response. New REQUIRED or RECOMMENDED attributes may be added
to the NFSv4 protocol as part of a new minor version by publishing a to the NFSv4 protocol as part of a new minor version by publishing a
standards-track RFC which allocates a new attribute number value and Standards Track RFC which allocates a new attribute number value and
defines the encoding for the attribute. See Section 11 for further defines the encoding for the attribute. See Section 11 for further
discussion. discussion.
Named attributes are accessed by the new OPENATTR operation, which Named attributes are accessed by the new OPENATTR operation, which
accesses a hidden directory of attributes associated with a file accesses a hidden directory of attributes associated with a file
system object. OPENATTR takes a filehandle for the object and system object. OPENATTR takes a filehandle for the object and
returns the filehandle for the attribute hierarchy. The filehandle returns the filehandle for the attribute hierarchy. The filehandle
for the named attributes is a directory object accessible by LOOKUP for the named attributes is a directory object accessible by LOOKUP
or READDIR and contains files whose names represent the named or READDIR and contains files whose names represent the named
attributes and whose data bytes are the value of the attribute. For attributes and whose data bytes are the value of the attribute. For
skipping to change at page 38, line 16 skipping to change at page 38, line 16
| LOOKUP | "foo" | ; look up file | | LOOKUP | "foo" | ; look up file |
| GETATTR | attrbits | | | GETATTR | attrbits | |
| OPENATTR | | ; access foo's named attributes | | OPENATTR | | ; access foo's named attributes |
| LOOKUP | "x11icon" | ; look up specific attribute | | LOOKUP | "x11icon" | ; look up specific attribute |
| READ | 0,4096 | ; read stream of bytes | | READ | 0,4096 | ; read stream of bytes |
+----------+-----------+---------------------------------+ +----------+-----------+---------------------------------+
Named attributes are intended for data needed by applications rather Named attributes are intended for data needed by applications rather
than by an NFS client implementation. NFS implementors are strongly than by an NFS client implementation. NFS implementors are strongly
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 REQUIRED is The set of attributes that are classified as REQUIRED is deliberately
deliberately small since servers must do whatever it takes to support small since servers need to do whatever it takes to support them. A
them. A server should support as many of the RECOMMENDED attributes server should support as many of the RECOMMENDED attributes as
as possible but by their definition, the server is not required to possible but, by their definition, the server is not required to
support all of them. Attributes are deemed REQUIRED if the data is support all of them. Attributes are deemed REQUIRED if the data is
both needed by a large number of clients and is not otherwise both needed by a large number of clients and is not otherwise
reasonably computable by the client when support is not provided on reasonably computable by the client when support is not provided on
the server. the server.
Note that the hidden directory returned by OPENATTR is a convenience Note that the hidden directory returned by OPENATTR is a convenience
for protocol processing. The client should not make any assumptions for protocol processing. The client should not make any assumptions
about the server's implementation of named attributes and whether the about the server's implementation of named attributes and whether or
underlying file system at the server has a named attribute directory not the underlying file system at the server has a named attribute
or not. Therefore, operations such as SETATTR and GETATTR on the directory. Therefore, operations such as SETATTR and GETATTR on the
named attribute directory are undefined. named attribute directory are undefined.
5.1. REQUIRED Attributes 5.1. REQUIRED Attributes
These MUST be supported by every NFSv4.0 client and server in order These MUST be supported by every NFSv4.0 client and server in order
to ensure a minimum level of interoperability. The server MUST store to ensure a minimum level of interoperability. The server MUST store
and return these attributes and the client MUST be able to function and return these attributes, and the client MUST be able to function
with an attribute set limited to these attributes. With just the with an attribute set limited to these attributes. With just the
REQUIRED attributes some client functionality may be impaired or REQUIRED attributes some client functionality may be impaired or
limited in some ways. A client may ask for any of these attributes limited in some ways. A client may ask for any of these attributes
to be returned by setting a bit in the GETATTR request and the server to be returned by setting a bit in the GETATTR request, and the
must return their value. server must return their value.
5.2. RECOMMENDED Attributes 5.2. RECOMMENDED Attributes
These attributes are understood well enough to warrant support in the These attributes are understood well enough to warrant support in the
NFSv4.0 protocol. However, they may not be supported on all clients NFSv4.0 protocol. However, they may not be supported on all clients
and servers. A client may ask for any of these attributes to be and servers. A client MAY ask for any of these attributes to be
returned by setting a bit in the GETATTR request but must handle the returned by setting a bit in the GETATTR request but must handle the
case where the server does not return them. A client may ask for the case where the server does not return them. A client MAY ask for the
set of attributes the server supports and SHOULD NOT request set of attributes the server supports and SHOULD NOT request
attributes the server does not support. A server should be tolerant attributes the server does not support. A server should be tolerant
of requests for unsupported attributes and simply not return them of requests for unsupported attributes and simply not return them
rather than considering the request an error. It is expected that rather than considering the request an error. It is expected that
servers will support all attributes they comfortably can and only servers will support all attributes they comfortably can and only
fail to support attributes which are difficult to support in their fail to support attributes that are difficult to support in their
operating environments. A server should provide attributes whenever operating environments. A server should provide attributes whenever
they don't have to "tell lies" to the client. For example, a file they don't have to "tell lies" to the client. For example, a file
modification time should be either an accurate time or should not be modification time should be either an accurate time or should not be
supported by the server. This will not always be comfortable to supported by the server. At times this will be difficult for
clients but the client is better positioned decide whether and how to clients, but a client is better positioned to decide whether and how
fabricate or construct an attribute or whether to do without the to fabricate or construct an attribute or whether to do without the
attribute. attribute.
5.3. Named Attributes 5.3. Named Attributes
These attributes are not supported by direct encoding in the NFSv4 These attributes are not supported by direct encoding in the NFSv4
protocol but are accessed by string names rather than numbers and protocol but are accessed by string names rather than numbers and
correspond to an uninterpreted stream of bytes which are stored with correspond to an uninterpreted stream of bytes that are stored with
the file system object. The name space for these attributes may be the file system object. The name space for these attributes may be
accessed by using the OPENATTR operation. The OPENATTR operation accessed by using the OPENATTR operation. The OPENATTR operation
returns a filehandle for a virtual "named attribute directory" and returns a filehandle for a virtual "named attribute directory", and
further perusal and modification of the name space may be done using further perusal and modification of the name space may be done using
operations that work on more typical directories. In particular, operations that work on more typical directories. In particular,
READDIR may be used to get a list of such named attributes and LOOKUP READDIR may be used to get a list of such named attributes, and
and OPEN may select a particular attribute. Creation of a new named LOOKUP and OPEN may select a particular attribute. Creation of a new
attribute may be the result of an OPEN specifying file creation. named attribute may be the result of an OPEN specifying file
creation.
Once an OPEN is done, named attributes may be examined and changed by Once an OPEN is done, named attributes may be examined and changed by
normal READ and WRITE operations using the filehandles and stateids normal READ and WRITE operations using the filehandles and stateids
returned by OPEN. returned by OPEN.
Named attributes and the named attribute directory may have their own Named attributes and the named attribute directory may have their own
(non-named) attributes. Each of objects must have all of the (non-named) attributes. Each of these objects must have all of the
REQUIRED attributes and may have additional RECOMMENDED attributes. REQUIRED attributes and may have additional RECOMMENDED attributes.
However, the set of attributes for named attributes and the named However, the set of attributes for named attributes and the named
attribute directory need not be as large as, and typically will not attribute directory need not be, and typically will not be, as large
be as large as that for other objects in that file system. as that for other objects in that file system.
Named attributes and the named attribute directory may be the target Named attributes and the named attribute directory might be the
of delegations (in the case of the named attribute directory these target of delegations (in the case of the named attribute directory
will be directory delegations). However, since granting of these will be directory delegations). However, since granting of
delegations or not is within the server's discretion, a server need delegations is at the server's discretion, a server need not support
not support delegations on named attributes or the named attribute delegations on named attributes or the named attribute directory.
directory.
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
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 that is also able to handle them should be able
to copy a file's data and metadata with complete transparency from to copy a file's data and metadata 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.
In NFSv4.0, the structure of named attribute directories is In NFSv4.0, the structure of named attribute directories is
restricted in a number of ways, in order to prevent the development restricted in a number of ways, in order to prevent the development
of non-interoperable implementations in which some servers support a of non-interoperable implementations in which some servers support a
fully general hierarchical directory structure for named attributes fully general hierarchical directory structure for named attributes
while others support a limited set, but fully adequate to the while others support a limited but adequate structure for named
feature's goals. In such an environment, clients or applications attributes. In such an environment, clients or applications might
might come to depend on non-portable extensions. The restrictions come to depend on non-portable extensions. The restrictions are:
are:
o CREATE is not allowed in a named attribute directory. Thus, such o CREATE is not allowed in a named attribute directory. Thus, such
objects as symbolic links and special files are not allowed to be objects as symbolic links and special files are not allowed to be
named attributes. Further, directories may not be created in a named attributes. Further, directories may not be created in a
named attribute directory so no hierarchical structure of named named attribute directory, so no hierarchical structure of named
attributes for a single object is allowed. attributes for a single object is allowed.
o If OPENATTR is done on a named attribute directory or on a named o If OPENATTR is done on a named attribute directory or on a named
attribute, the server MUST return NFS4ERR_WRONG_TYPE. attribute, the server MUST return NFS4ERR_WRONG_TYPE.
o Doing a RENAME of a named attribute to a different named attribute o Doing a RENAME of a named attribute to a different named attribute
directory or to an ordinary (i.e., non-named-attribute) directory directory or to an ordinary (i.e., non-named-attribute) directory
is not allowed. is not allowed.
o Creating hard links between named attribute directories or between o Creating hard links between named attribute directories or between
named attribute directories and ordinary directories is not named attribute directories and ordinary directories is not
allowed. allowed.
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 Section 18 for further IETF Standards Track documents. See Section 18 for further
discussion. discussion.
5.4. Classification of Attributes 5.4. Classification of Attributes
Each of the REQUIRED and RECOMMENDED attributes can be classified in Each of the REQUIRED and RECOMMENDED attributes can be classified in
one of three categories: per server, per file system, or per file one of three categories: per server (i.e., the value of the attribute
system object. Note that it is possible that some per file system will be the same for all file objects that share the same server),
attributes may vary within the file system. See the "homogeneous" per file system (i.e., the value of the attribute will be the same
attribute for its definition. Note that the attributes for some or all file objects that share the same fsid attribute
time_access_set and time_modify_set are not listed in this section (Section 5.8.1.9) and server owner), or per file system object. Note
because they are write-only attributes corresponding to time_access that it is possible that some per file system attributes may vary
and time_modify, and are used in a special instance of SETATTR. within the file system. Note that it is possible that some per file
system attributes may vary within the file system, depending on the
value of the "homogeneous" (Section 5.8.2.16) attribute. Note that
the attributes time_access_set and time_modify_set are not listed in
this section because they are write-only attributes corresponding to
time_access and time_modify, and are used in a special instance of
SETATTR.
o The per server attribute is: o The per-server attribute is:
lease_time lease_time
o The per file system attributes are: o The per-file system attributes are:
supported_attrs, fh_expire_type, link_support, symlink_support, supported_attrs, fh_expire_type, link_support, symlink_support,
unique_handles, aclsupport, cansettime, case_insensitive, unique_handles, aclsupport, cansettime, case_insensitive,
case_preserving, chown_restricted, files_avail, files_free, case_preserving, chown_restricted, files_avail, files_free,
files_total, fs_locations, homogeneous, maxfilesize, maxname, files_total, fs_locations, homogeneous, maxfilesize, maxname,
maxread, maxwrite, no_trunc, space_avail, space_free, maxread, maxwrite, no_trunc, space_avail, space_free,
space_total, time_delta, space_total, time_delta,
o The per file system object attributes are: o The per-file system object attributes are:
type, change, size, named_attr, fsid, rdattr_error, filehandle, type, change, size, named_attr, fsid, rdattr_error, filehandle,
acl, archive, fileid, hidden, maxlink, mimetype, mode, acl, archive, fileid, hidden, maxlink, mimetype, mode,
numlinks, owner, owner_group, rawdev, space_used, system, numlinks, owner, owner_group, rawdev, space_used, system,
time_access, time_backup, time_create, time_metadata, time_access, time_backup, time_create, time_metadata,
time_modify, mounted_on_fileid time_modify, mounted_on_fileid
For quota_avail_hard, quota_avail_soft, and quota_used see their For quota_avail_hard, quota_avail_soft, and quota_used, see their
definitions below for the appropriate classification. definitions below for the appropriate classification.
5.5. Set-Only and Get-Only Attributes 5.5. Set-Only and Get-Only Attributes
Some REQUIRED and RECOMMENDED attributes are set-only, i.e., they can Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they can
be set via SETATTR but not retrieved via GETATTR. Similarly, some be set via SETATTR but not retrieved via GETATTR. Similarly, some
REQUIRED and RECOMMENDED attributes are get-only, i.e., they can be REQUIRED and RECOMMENDED attributes are get-only; i.e., they can be
retrieved GETATTR but not set via SETATTR. If a client attempts to retrieved via GETATTR but not set via SETATTR. If a client attempts
set a get-only attribute or get a set-only attributes, the server to set a get-only attribute or get a set-only attribute, the server
MUST return NFS4ERR_INVAL. MUST return NFS4ERR_INVAL.
5.6. REQUIRED Attributes - List and Definition References 5.6. REQUIRED Attributes - List and Definition References
The list of REQUIRED attributes appears in Table 2. The meaning of The list of REQUIRED attributes appears in Table 2. The meaning of
the columns of the table are: the columns of the table are:
o Name: the name of attribute o Name: The name of attribute
o Id: the number assigned to the attribute. In the event of o Id: The number assigned to the attribute. In the event of
conflicts between the assigned number and [2], the latter is conflicts between the assigned number and [2], the latter is
authoritative. likely authoritative, but should be resolved with Errata to this
document and/or [2]. See [25] for the Errata process.
o Data Type: The XDR data type of the attribute. o Data Type: The XDR data type of the attribute.
o Acc: Access allowed to the attribute. R means read-only (GETATTR o Acc: Access allowed to the attribute. R means read-only (GETATTR
may retrieve, SETATTR may not set). W means write-only (SETATTR may retrieve, SETATTR may not set). W means write-only (SETATTR
may set, GETATTR may not retrieve). R W means read/write (GETATTR may set, GETATTR may not retrieve). R W means read/write (GETATTR
may retrieve, SETATTR may set). may retrieve, SETATTR may set).
o Defined in: the section of this specification that describes the o Defined in: The section of this specification that describes the
attribute. attribute.
+-----------------+----+------------+-----+------------------+ +-----------------+----+------------+-----+------------------+
| Name | Id | Data Type | Acc | Defined in: | | Name | Id | Data Type | Acc | Defined in: |
+-----------------+----+------------+-----+------------------+ +-----------------+----+------------+-----+------------------+
| supported_attrs | 0 | bitmap4 | R | Section 5.8.1.1 | | supported_attrs | 0 | bitmap4 | R | Section 5.8.1.1 |
| type | 1 | nfs_ftype4 | R | Section 5.8.1.2 | | type | 1 | nfs_ftype4 | R | Section 5.8.1.2 |
| fh_expire_type | 2 | uint32_t | R | Section 5.8.1.3 | | fh_expire_type | 2 | uint32_t | R | Section 5.8.1.3 |
| change | 3 | uint64_t | R | Section 5.8.1.4 | | change | 3 | uint64_t | R | Section 5.8.1.4 |
| size | 4 | uint64_t | R W | Section 5.8.1.5 | | size | 4 | uint64_t | R W | Section 5.8.1.5 |
skipping to change at page 43, line 44 skipping to change at page 43, line 48
+-------------------+----+--------------+-----+------------------+ +-------------------+----+--------------+-----+------------------+
Table 3 Table 3
5.8. Attribute Definitions 5.8. Attribute Definitions
5.8.1. Definitions of REQUIRED Attributes 5.8.1. Definitions of REQUIRED Attributes
5.8.1.1. Attribute 0: supported_attrs 5.8.1.1. Attribute 0: supported_attrs
The bit vector which would retrieve all REQUIRED and RECOMMENDED The bit vector that would retrieve all REQUIRED and RECOMMENDED
attributes that are supported for this object. The scope of this attributes that are supported for this object. The scope of this
attribute applies to all objects with a matching fsid. attribute applies to all objects with a matching fsid.
5.8.1.2. Attribute 1: type 5.8.1.2. Attribute 1: type
Designates the type of an object in terms of one of a number of Designates the type of an object in terms of one of a number of
special constants: special constants:
o NF4REG designates a regular file. o NF4REG designates a regular file.
skipping to change at page 44, line 26 skipping to change at page 44, line 31
o NF4FIFO designates a fifo special file. o NF4FIFO designates a fifo special file.
o NF4ATTRDIR designates a named attribute directory. o NF4ATTRDIR designates a named attribute directory.
o NF4NAMEDATTR designates a named attribute. o NF4NAMEDATTR designates a named attribute.
Within the explanatory text and operation descriptions, the following Within the explanatory text and operation descriptions, the following
phrases will be used with the meanings given below: phrases will be used with the meanings given below:
o The phrase "is a directory" means that the object is of type o The phrase "is a directory" means that the object's type attribute
NF4DIR or of type NF4ATTRDIR. is NF4DIR or NF4ATTRDIR.
o The phrase "is a special file" means that the object is of one of o The phrase "is a special file" means that the object's type
the types NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO.
o The phrase "is an ordinary file" means that the object is of type o The phrase "is an ordinary file" means that the object's type
NF4REG or of type NF4NAMEDATTR. attribute is NF4REG or NF4NAMEDATTR.
5.8.1.3. Attribute 2: fh_expire_type 5.8.1.3. Attribute 2: fh_expire_type
Server uses this to specify filehandle expiration behavior to the Server uses this to specify filehandle expiration behavior to the
client. See Section 4 for additional description. client. See Section 4 for additional description.
5.8.1.4. Attribute 3: change 5.8.1.4. Attribute 3: change
A value created by the server that the client can use to determine if A value created by the server that the client can use to determine if
file data, directory contents or attributes of the object have been file data, directory contents, or attributes of the object have been
modified. The server may return the object's time_metadata attribute modified. The server may return the object's time_metadata attribute
for this attribute's value but only if the file system object can not for this attribute's value but only if the file system object cannot
be updated more frequently than the resolution of time_metadata. be updated more frequently than the resolution of time_metadata.
5.8.1.5. Attribute 4: size 5.8.1.5. Attribute 4: size
The size of the object in bytes. The size of the object in bytes.
5.8.1.6. Attribute 5: link_support 5.8.1.6. Attribute 5: link_support
True, if the object's file system supports hard links. TRUE, if the object's file system supports hard links.
5.8.1.7. Attribute 6: symlink_support 5.8.1.7. Attribute 6: symlink_support
True, if the object's file system supports symbolic links. TRUE, if the object's file system supports symbolic links.
5.8.1.8. Attribute 7: named_attr 5.8.1.8. Attribute 7: named_attr
True, if this object has named attributes. In other words, object TRUE, if this object has named attributes. In other words, object
has a non-empty named attribute directory. has a non-empty named attribute directory.
5.8.1.9. Attribute 8: fsid 5.8.1.9. Attribute 8: fsid
Unique file system identifier for the file system holding this Unique file system identifier for the file system holding this
object. fsid contains major and minor components each of which are of object. The fsid attribute has major and minor components, each of
data type uint64_t. which are of data type uint64_t.
5.8.1.10. Attribute 9: unique_handles 5.8.1.10. Attribute 9: unique_handles
True, if two distinct filehandles guaranteed to refer to two TRUE, if two distinct filehandles are guaranteed to refer to two
different file system objects. different file system objects.
5.8.1.11. Attribute 10: lease_time 5.8.1.11. Attribute 10: lease_time
Duration of leases at server in seconds. Duration of the lease at server in seconds.
5.8.1.12. Attribute 11: rdattr_error 5.8.1.12. Attribute 11: rdattr_error
Error returned from an attempt to retrieve attributes during a Error returned from an attempt to retrieve attributes during a
READDIR operation. READDIR operation.
5.8.1.13. Attribute 19: filehandle 5.8.1.13. Attribute 19: filehandle
The filehandle of this object (primarily for READDIR requests). The filehandle of this object (primarily for READDIR requests).
5.8.2. Definitions of Uncategorized RECOMMENDED Attributes 5.8.2. Definitions of Uncategorized RECOMMENDED Attributes
The definitions of most of the RECOMMENDED attributes follow. The definitions of most of the RECOMMENDED attributes follow.
Collections that share a common category are defined in other Collections that share a common category are defined in other
sections. sections.
5.8.2.1. Attribute 14: archive 5.8.2.1. Attribute 14: archive
True, if this file has been archived since the time of last TRUE, if this file has been archived since the time of last
modification (deprecated in favor of time_backup). modification (deprecated in favor of time_backup).
5.8.2.2. Attribute 15: cansettime 5.8.2.2. Attribute 15: cansettime
True, if the server able to change the times for a file system object TRUE, if the server is able to change the times for a file system
as specified in a SETATTR operation. object as specified in a SETATTR operation.
5.8.2.3. Attribute 16: case_insensitive 5.8.2.3. Attribute 16: case_insensitive
True, if file name comparisons on this file system are case TRUE, if file name comparisons on this file system are case
insensitive. insensitive.
5.8.2.4. Attribute 17: case_preserving 5.8.2.4. Attribute 17: case_preserving
True, if file name case on this file system is preserved. TRUE, if file name case on this file system is preserved.
5.8.2.5. Attribute 18: chown_restricted 5.8.2.5. Attribute 18: chown_restricted
If TRUE, the server will reject any request to change either the If TRUE, the server will reject any request to change either the
owner or the group associated with a file if the caller is not a owner or the group associated with a file if the caller is not a
privileged user (for example, "root" in UNIX operating environments privileged user (for example, "root" in UNIX operating environments
or in Windows 2000 the "Take Ownership" privilege). or in Windows 2000, the "Take Ownership" privilege).
5.8.2.6. Attribute 20: fileid 5.8.2.6. Attribute 20: fileid
A number uniquely identifying the file within the file system. A number uniquely identifying the file within the file system.
5.8.2.7. Attribute 21: files_avail 5.8.2.7. Attribute 21: files_avail
File slots available to this user on the file system containing this File slots available to this user on the file system containing this
object - this should be the smallest relevant limit. object -- this should be the smallest relevant limit.
5.8.2.8. Attribute 22: files_free 5.8.2.8. Attribute 22: files_free
Free file slots on the file system containing this object - this Free file slots on the file system containing this object - this
should be the smallest relevant limit. should be the smallest relevant limit.
5.8.2.9. Attribute 23: files_total 5.8.2.9. Attribute 23: files_total
Total file slots on the file system containing this object. Total file slots on the file system containing this object.
5.8.2.10. Attribute 24: fs_locations 5.8.2.10. Attribute 24: fs_locations
Locations where this file system may be found. If the server returns Locations where this file system may be found. If the server returns
NFS4ERR_MOVED as an error, this attribute MUST be supported. NFS4ERR_MOVED as an error, this attribute MUST be supported.
5.8.2.11. Attribute 25: hidden 5.8.2.11. Attribute 25: hidden
True, if the file is considered hidden with respect to the Windows TRUE, if the file is considered hidden with respect to the Windows
API. API.
5.8.2.12. Attribute 26: homogeneous 5.8.2.12. Attribute 26: homogeneous
True, if this object's file system is homogeneous, i.e., are per file TRUE, if this object's file system is homogeneous, i.e., all objects
system attributes the same for all file system's objects. in the file system (all objects on the server with the same fsid)
have common values for all per-file-system attributes.
5.8.2.13. Attribute 27: maxfilesize 5.8.2.13. Attribute 27: maxfilesize
Maximum supported file size for the file system of this object. Maximum supported file size for the file system of this object.
5.8.2.14. Attribute 28: maxlink 5.8.2.14. Attribute 28: maxlink
Maximum number of links for this object. Maximum number of links for this object.
5.8.2.15. Attribute 29: maxname 5.8.2.15. Attribute 29: maxname
Maximum file name size supported for this object. Maximum file name size supported for this object.
5.8.2.16. Attribute 30: maxread 5.8.2.16. Attribute 30: maxread
Maximum read size supported for this object. Maximum amount of data the READ operation will return for this
object.
5.8.2.17. Attribute 31: maxwrite 5.8.2.17. Attribute 31: maxwrite
Maximum write size supported for this object. This attribute SHOULD Maximum amount of data the WRITE operation will accept for this
be supported if the file is writable. Lack of this attribute can object. This attribute SHOULD be supported if the file is writable.
lead to the client either wasting bandwidth or not receiving the best Lack of this attribute can lead to the client either wasting
performance. bandwidth or not receiving the best performance.
5.8.2.18. Attribute 32: mimetype 5.8.2.18. Attribute 32: mimetype
MIME body type/subtype of this object. MIME body type/subtype of this object.
5.8.2.19. Attribute 55: mounted_on_fileid 5.8.2.19. Attribute 55: mounted_on_fileid
Like fileid, but if the target filehandle is the root of a file Like fileid, but if the target filehandle is the root of a file
system, this attribute represents the fileid of the underlying system, this attribute represents the fileid of the underlying
directory. directory.
UNIX-based operating environments connect a file system into the UNIX-based operating environments connect a file system into the
namespace by connecting (mounting) the file system onto the existing namespace by connecting (mounting) the file system onto the existing
file object (the mount point, usually a directory) of an existing file object (the mount point, usually a directory) of an existing
file system. When the mount point's parent directory is read via an file system. When the mount point's parent directory is read via an
API like readdir(), the return results are directory entries, each API like readdir(), the return results are directory entries, each
with a component name and a fileid. The fileid of the mount point's with a component name and a fileid. The fileid of the mount point's
directory entry will be different from the fileid that the stat() directory entry will be different from the fileid that the stat()
system call returns. The stat() system call is returning the fileid system call returns. The stat() system call is returning the fileid
of the root of the mounted file system, whereas readdir() is of the root of the mounted file system, whereas readdir() is
returning the fileid stat() would have returned before any file returning the fileid that stat() would have returned before any file
systems were mounted on the mount point. systems were mounted on the mount point.
Unlike NFSv3, NFSv4.0 allows a client's LOOKUP request to cross other Unlike NFSv3, NFSv4.0 allows a client's LOOKUP request to cross other
file systems. The client detects the file system crossing whenever file systems. The client detects the file system crossing whenever
the filehandle argument of LOOKUP has an fsid attribute different the filehandle argument of LOOKUP has an fsid attribute different
from that of the filehandle returned by LOOKUP. A UNIX-based client from that of the filehandle returned by LOOKUP. A UNIX-based client
will consider this a "mount point crossing". UNIX has a legacy will consider this a "mount point crossing". UNIX has a legacy
scheme for allowing a process to determine its current working scheme for allowing a process to determine its current working
directory. This relies on readdir() of a mount point's parent and directory. This relies on readdir() of a mount point's parent and
stat() of the mount point returning fileids as previously described. stat() of the mount point returning fileids as previously described.
skipping to change at page 49, line 19 skipping to change at page 49, line 25
5.8.2.22. Attribute 36: owner 5.8.2.22. Attribute 36: owner
The string name of the owner of this object. The string name of the owner of this object.
5.8.2.23. Attribute 37: owner_group 5.8.2.23. Attribute 37: owner_group
The string name of the group ownership of this object. The string name of the group ownership of this object.
5.8.2.24. Attribute 38: quota_avail_hard 5.8.2.24. Attribute 38: quota_avail_hard
The value in bytes which represents the amount of additional disk The value in bytes that represents the amount of additional disk
space beyond the current allocation that can be allocated to this space beyond the current allocation that can be allocated to this
file or directory before further allocations will be refused. It is file or directory before further allocations will be refused. It is
understood that this space may be consumed by allocations to other understood that this space may be consumed by allocations to other
files or directories. files or directories.
5.8.2.25. Attribute 39: quota_avail_soft 5.8.2.25. Attribute 39: quota_avail_soft
The value in bytes which represents the amount of additional disk The value in bytes that represents the amount of additional disk
space that can be allocated to this file or directory before the user space that can be allocated to this file or directory before the user
may reasonably be warned. It is understood that this space may be may reasonably be warned. It is understood that this space may be
consumed by allocations to other files or directories though there is consumed by allocations to other files or directories though there is
a rule as to which other files or directories. a rule as to which other files or directories.
5.8.2.26. Attribute 40: quota_used 5.8.2.26. Attribute 40: quota_used
The value in bytes which represent the amount of disc space used by The value in bytes that represents the amount of disc space used by
this file or directory and possibly a number of other similar files this file or directory and possibly a number of other similar files
or directories, where the set of "similar" meets at least the or directories, where the set of "similar" meets at least the
criterion that allocating space to any file or directory in the set criterion that allocating space to any file or directory in the set
will reduce the "quota_avail_hard" of every other file or directory will reduce the "quota_avail_hard" of every other file or directory
in the set. in the set.
Note that there may be a number of distinct but overlapping sets of Note that there may be a number of distinct but overlapping sets of
files or directories for which a quota_used value is maintained. files or directories for which a quota_used value is maintained, e.g.
E.g. "all files with a given owner", "all files with a given group "all files with a given owner", "all files with a given group owner".
owner". etc. etc. The server is at liberty to choose any of those sets when
providing the content of the quota_used attribute, but should do so
The server is at liberty to choose any of those sets but should do so
in a repeatable way. The rule may be configured per file system or in a repeatable way. The rule may be configured per file system or
may be "choose the set with the smallest quota". may be "choose the set with the smallest quota".
5.8.2.27. Attribute 41: rawdev 5.8.2.27. Attribute 41: rawdev
Raw device identifier; the UNIX device major/minor node information. Raw device number of file of type NF4BLK or NF4CHR. The device
If the value of type is not NF4BLK or NF4CHR, the value returned number is split into major and minor numbers. If the file's type
SHOULD NOT be considered useful. attribute is not NF4BLK or NF4CHR, the value returned SHOULD NOT be
considered useful.
5.8.2.28. Attribute 42: space_avail 5.8.2.28. Attribute 42: space_avail
Disk space in bytes available to this user on the file system Disk space in bytes available to this user on the file system
containing this object - this should be the smallest relevant limit. containing this object -- this should be the smallest relevant limit.
5.8.2.29. Attribute 43: space_free 5.8.2.29. Attribute 43: space_free
Free disk space in bytes on the file system containing this object - Free disk space in bytes on the file system containing this object --
this should be the smallest relevant limit. this should be the smallest relevant limit.
5.8.2.30. Attribute 44: space_total 5.8.2.30. Attribute 44: space_total
Total disk space in bytes on the file system containing this object. Total disk space in bytes on the file system containing this object.
5.8.2.31. Attribute 45: space_used 5.8.2.31. Attribute 45: space_used
Number of file system bytes allocated to this object. Number of file system bytes allocated to this object.
5.8.2.32. Attribute 46: system 5.8.2.32. Attribute 46: system
This attribute is TRUE if this file is a "system" file with respect This attribute is TRUE if this file is a "system" file with respect
to the Windows operating environment. to the Windows operating environment.
5.8.2.33. Attribute 47: time_access 5.8.2.33. Attribute 47: time_access
The time_access attribute represents the time of last access to the The time_access attribute represents the time of last access to the
object by a read that was satisfied by the server. The notion of object by a READ operation sent to the server. The notion of what is
what is an "access" depends on server's operating environment and/or an "access" depends on the server's operating environment and/or the
the server's file system semantics. For example, for servers obeying server's file system semantics. For example, for servers obeying
POSIX semantics, time_access would be updated only by the READLINK, Portable Operating System Interface (POSIX) semantics, time_access
READ, and READDIR operations and not any of the operations that would be updated only by the READ and READDIR operations and not any
modify the content of the object. Of course, setting the of the operations that modify the content of the object [16], [17],
corresponding time_access_set attribute is another way to modify the [26], [27], [28]. Of course, setting the corresponding
time_access attribute. time_access_set attribute is another way to modify the time_access
attribute.
Whenever the file object resides on a writable file system, the Whenever the file object resides on a writable file system, the
server should make best efforts to record time_access into stable server should make its best efforts to record time_access into stable
storage. However, to mitigate the performance effects of doing so, storage. However, to mitigate the performance effects of doing so,
and most especially whenever the server is satisfying the read of the and most especially whenever the server is satisfying the read of the
object's content from its cache, the server MAY cache access time object's content from its cache, the server MAY cache access time
updates and lazily write them to stable storage. It is also updates and lazily write them to stable storage. It is also
acceptable to give administrators of the server the option to disable acceptable to give administrators of the server the option to disable
time_access updates. time_access updates.
5.8.2.34. Attribute 48: time_access_set 5.8.2.34. Attribute 48: time_access_set
Set the time of last access to the object. SETATTR use only. Sets the time of last access to the object. SETATTR use only.
5.8.2.35. Attribute 49: time_backup 5.8.2.35. Attribute 49: time_backup
The time of last backup of the object. The time of last backup of the object.
5.8.2.36. Attribute 50: time_create 5.8.2.36. Attribute 50: time_create
The time of creation of the object. This attribute does not have any The time of creation of the object. This attribute does not have any
relation to the traditional UNIX file attribute "ctime" or "change relation to the traditional UNIX file attribute "ctime" or "change
time". time".
skipping to change at page 51, line 34 skipping to change at page 51, line 39
5.8.2.38. Attribute 52: time_metadata 5.8.2.38. Attribute 52: time_metadata
The time of last metadata modification of the object. The time of last metadata modification of the object.
5.8.2.39. Attribute 53: time_modify 5.8.2.39. Attribute 53: time_modify
The time of last modification to the object. The time of last modification to the object.
5.8.2.40. Attribute 54: time_modify_set 5.8.2.40. Attribute 54: time_modify_set
Set the time of last modification to the object. SETATTR use only. Sets the time of last modification to the object. SETATTR use only.
5.9. Interpreting owner and owner_group 5.9. Interpreting owner and owner_group
The RECOMMENDED attributes "owner" and "owner_group" (and also users The RECOMMENDED attributes "owner" and "owner_group" (and also users
and groups within the "acl" attribute) are represented in terms of a and groups within the "acl" attribute) are represented in terms of a
UTF-8 string. To avoid a representation that is tied to a particular UTF-8 string. To avoid a representation that is tied to a particular
underlying implementation at the client or server, the use of the underlying implementation at the client or server, the use of the
UTF-8 string has been chosen. Note that section 6.1 of RFC2624 [25] UTF-8 string has been chosen. Note that section 6.1 of RFC 2624 [29]
provides additional rationale. It is expected that the client and provides additional rationale. It is expected that the client and
server will have their own local representation of owner and server will have their own local representation of owner and
owner_group that is used for local storage or presentation to the end owner_group that is used for local storage or presentation to the end
user. Therefore, it is expected that when these attributes are 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, the local representation
representation is translated to a syntax of the form "user@ is translated to a syntax of the form "user@dns_domain". This will
dns_domain". This will allow for a client and server that do not use allow for a client and server that do not use the same local
the same local representation the ability to translate to a common representation the ability to translate to a common syntax that can
syntax that can be interpreted by both. be interpreted by both.
Similarly, security principals may be represented in different ways Similarly, security principals may be represented in different ways
by different security mechanisms. Servers normally translate these by different security mechanisms. Servers normally translate these
representations into a common format, generally that used by local representations into a common format, generally that used by local
storage, to serve as a means of identifying the users corresponding storage, to serve as a means of identifying the users corresponding
to these security principals. When these local identifiers are to these security principals. When these local identifiers are
translated to the form of the owner attribute, associated with files translated to the form of the owner attribute, associated with files
created by such principals they identify, in a common format, the created by such principals, they identify, in a common format, the
users associated with each corresponding set of security principals. users associated with each corresponding set of security principals.
The translation used to interpret owner and group strings is not The translation used to interpret owner and group strings is not
specified as part of the protocol. This allows various solutions to specified as part of the protocol. This allows various solutions to
be employed. For example, a local translation table may be consulted be employed. For example, a local translation table may be consulted
that maps between a numeric identifier to the user@dns_domain syntax. that maps a numeric identifier to the user@dns_domain syntax. A name
A name service may also be used to accomplish the translation. A service may also be used to accomplish the translation. A server may
server may provide a more general service, not limited by any provide a more general service, not limited by any particular
particular translation (which would only translate a limited set of translation (which would only translate a limited set of possible
possible strings) by storing the owner and owner_group attributes in strings) by storing the owner and owner_group attributes in local
local storage without any translation or it may augment a translation storage without any translation or it may augment a translation
method by storing the entire string for attributes for which no method by storing the entire string for attributes for which no
translation is available while using the local representation for translation is available while using the local representation for
those cases in which a translation is available. those cases in which a translation is available.
Servers that do not provide support for all possible values of the Servers that do not provide support for all possible values of the
owner and owner_group attributes, SHOULD return an error owner and owner_group attributes SHOULD return an error
(NFS4ERR_BADOWNER) when a string is presented that has no (NFS4ERR_BADOWNER) when a string is presented that has no
translation, as the value to be set for a SETATTR of the owner, translation, as the value to be set for a SETATTR of the owner,
owner_group, or acl attributes. When a server does accept an owner owner_group, or acl attributes. When a server does accept an owner
or owner_group value as valid on a SETATTR (and similarly for the or owner_group value as valid on a SETATTR (and similarly for the
owner and group strings in an acl), it needs to try to return that owner and group strings in an acl), it is promising to return that
same string for which see below) when a corresponding GETATTR is same string for which see below) when a corresponding GETATTR is
done. For some internationalization-related exceptions where this is done. For some internationalization-related exceptions where this is
not possible, see below. Configuration changes (including changes not possible, see below. Configuration changes (including changes
from the mapping of the string to the local representation) and ill- from the mapping of the string to the local representation) and ill-
constructed name translations (those that contain aliasing) may make constructed name translations (those that contain aliasing) may make
that promise impossible to honor. Servers should make appropriate that promise impossible to honor. Servers should make appropriate
efforts to avoid a situation in which these attributes have their efforts to avoid a situation in which these attributes have their
values changed when no real change to ownership has occurred. values changed when no real change to ownership has occurred.
The "dns_domain" portion of the owner string is meant to be a DNS The "dns_domain" portion of the owner string is meant to be a DNS
domain name. For example, user@ietf.org. Servers should accept as domain name. For example, user@example.org. Servers should accept
valid a set of users for at least one domain. A server may treat 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 other domains as having no valid translations. A more general
service is provided when a server is capable of accepting users for service is provided when a server is capable of accepting users for
multiple domains, or for all domains, subject to security multiple domains, or for all domains, subject to security
constraints. constraints.
As mentioned above, it is desirable that a server when accepting a As mentioned above, it is desirable that a server when accepting a
string of the form user@domain or group@domain in an attribute, string of the form user@domain or group@domain in an attribute,
return this same string when that corresponding attribute is fetched. return this same string when that corresponding attribute is fetched.
Internationalization issues (for a general discussion of which see Internationalization issues (for a general discussion of which see
Section 12) make this impossible and the client needs to take note of Section 12) make this impossible and the client needs to take note of
skipping to change at page 53, line 18 skipping to change at page 53, line 24
o The string representing the domain may be converted to equivalent o The string representing the domain may be converted to equivalent
U-label, if presented using a form other a a U-label. See U-label, if presented using a form other a a U-label. See
Section 12.6 for details. Section 12.6 for details.
o The user or group may be returned in a different form, due to o The user or group may be returned in a different form, due to
normalization issues, although it will always be a canonically normalization issues, although it will always be a canonically
equivalent string. See See Section 12.7.3 for details. equivalent string. See See Section 12.7.3 for details.
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 will 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 at the sender attribute signifies that no translation was available at the sender
and that the receiver of the attribute should not use that string as and that the receiver of the attribute should not use that string as
a basis for translation into its own internal format. Even though a basis for translation into its own internal format. Even though
the attribute value can not be translated, it may still be useful. the attribute value cannot be translated, it may still be useful. In
In the case of a client, the attribute string may be used for local the case of a client, the attribute string may be used for local
display of ownership. display of ownership.
To provide a greater degree of compatibility with NFSv3, which To provide a greater degree of compatibility with NFSv3, which
identified users and groups by 32-bit unsigned user identifiers and identified users and groups by 32-bit unsigned user identifiers and
group identifiers, owner and group strings that consist of decimal group identifiers, owner and group strings that consist of decimal
numeric values with no leading zeros can be given a special numeric values with no leading zeros can be given a special
interpretation by clients and servers which choose to provide such interpretation by clients and servers that choose to provide such
support. The receiver may treat such a user or group string as support. The receiver may treat such a user or group string as
representing the same user as would be represented by an NFSv3 uid or representing the same user as would be represented by an NFSv3 uid or
gid having the corresponding numeric value. A server is not gid having the corresponding numeric value. A server is not
obligated to accept such a string, but may return an NFS4ERR_BADOWNER obligated to accept such a string, but may return an NFS4ERR_BADOWNER
instead. To avoid this mechanism being used to subvert user and instead. To avoid this mechanism being used to subvert user and
group translation, so that a client might pass all of the owners 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 groups in numeric form, a server SHOULD return an NFS4ERR_BADOWNER
error when there is a valid translation for the user or owner error when there is a valid translation for the user or owner
designated in this way. In that case, the client must use the designated in this way. In that case, the client must use the
appropriate name@domain string and not the special form for appropriate name@domain string and not the special form for
compatibility. compatibility.
The owner string "nobody" may be used to designate an anonymous user, The owner string "nobody" may be used to designate an anonymous user,
which will be associated with a file created by a security principal which will be associated with a file created by a security principal
that cannot be mapped through normal means to the owner attribute. that cannot be mapped through normal means to the owner attribute.
5.10. Character Case Attributes 5.10. 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 [26] which may or may not include the word "CAPITAL" or name" RFC1345 [30] which may or may not include 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, although insensitive comparisons, and non-case-preserving storage, although
there are variations that occur additional characters with a name there are variations that occur additional characters with a name
including "SMALL" or "CAPITAL" are added in a subsequent version of including "SMALL" or "CAPITAL" are added in a subsequent version of
Unicode. Unicode.
For general character handling and internationalization issues, see For general character handling and internationalization issues, see
Section 12. For details regarding case mapping, see the section Section 12. For details regarding case mapping, see the section
Case-based Mapping Used for Component4 Strings. Case-based Mapping Used for Component4 Strings.
skipping to change at page 83, line 39 skipping to change at page 84, line 9
limit the changes seen by the client, to those that are less limit the changes seen by the client, to those that are less
aggressive, use more standard methods of replicating data, and impose aggressive, use more standard methods of replicating data, and impose
a greater burden on the client to adapt to the transition. a greater burden on the client to adapt to the transition.
The NFSv4 protocol does not impose choices on clients and servers The NFSv4 protocol does not impose choices on clients and servers
with regard to that spectrum of transition methods. In fact, there with regard to that spectrum of transition methods. In fact, there
are many valid choices, depending on client and application are many valid choices, depending on client and application
requirements and their interaction with server implementation requirements and their interaction with server implementation
choices. The NFSv4.0 protocol does not provide the servers a means choices. The NFSv4.0 protocol does not provide the servers a means
of communicating the transition methods. In the NFSv4.1 protocol of communicating the transition methods. In the NFSv4.1 protocol
[27], an additional attribute "fs_locations_info" is presented, which [31], an additional attribute "fs_locations_info" is presented, which
will define the specific choices that can be made, how these choices will define the specific choices that can be made, how these choices
are communicated to the client, and how the client is to deal with are communicated to the client, and how the client is to deal with
any discontinuities. any discontinuities.
In the sections below, references will be made to various possible In the sections below, references will be made to various possible
server implementation choices as a way of illustrating the transition server implementation choices as a way of illustrating the transition
scenarios that clients may deal with. The intent here is not to scenarios that clients may deal with. The intent here is not to
define or limit server implementations but rather to illustrate the define or limit server implementations but rather to illustrate the
range of issues that clients may face. Again, as the NFSv4.0 range of issues that clients may face. Again, as the NFSv4.0
protocol does not have an explict means of communicating these issues protocol does not have an explict means of communicating these issues
skipping to change at page 104, line 27 skipping to change at page 104, line 43
For the case of the use of multiple, disjoint security mechanisms in For the case of the use of multiple, disjoint security mechanisms in
the server's resources, the security for a particular object in the the server's resources, the security for a particular object in the
server's namespace should be the union of all security mechanisms of server's namespace should be the union of all security mechanisms of
all direct descendants. all direct descendants.
9. File Locking and Share Reservations 9. 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
stateful. With the inclusion of share reservations the protocol stateful. With the inclusion of share reservations 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 [28]. There are three components to combination of NFS and NLM [32]. 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
o Ability to reliably detect inconsistency in state between client o Ability to reliably detect inconsistency in state between client
and server and server
o Simple and robust recovery mechanisms o Simple and robust recovery mechanisms
In this model, the server owns the state information. The client In this model, the server owns the state information. The client
skipping to change at page 112, line 48 skipping to change at page 113, line 16
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
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
integer. Different lock_owners have different sequences. The server integer. Different lock_owners have different sequences. The server
maintains the last sequence number (L) received and the response that maintains the last sequence number (L) received and the response that
was returned. The first request issued for any given lock_owner is was returned. The server is free to assign any value for the first
issued with a sequence number of zero. request issued for any given lock_owner.
Note that for requests that contain a sequence number, for each Note that for requests that contain a sequence number, for each
lock_owner, there should be no more than one outstanding request. lock_owner, there should be no more than one outstanding request.
If a request (r) with a previous sequence number (r < L) is received, If a request (r) with a previous sequence number (r < L) is received,
it 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 SETCLIENTID/SETCLIENTID_CONFIRM history is reinitialized whenever the SETCLIENTID/SETCLIENTID_CONFIRM
sequence changes the client verifier. sequence changes the client verifier.
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. For an example of modulo arithmetic involving sequence numbers 2^32. For an example of modulo arithmetic involving sequence numbers
see [29]. see [33].
It is critical the server maintain the last response sent to the It is critical the server maintain the last response sent to the
client to provide a more reliable cache of duplicate non-idempotent client to provide a more reliable cache of duplicate non-idempotent
requests than that of the traditional cache described in [30]. The requests than that of the traditional cache described in [34]. The
traditional duplicate request cache uses a least recently used traditional duplicate request cache uses a least recently used
algorithm for removing unneeded requests. However, the last lock algorithm for removing unneeded requests. However, the last lock
request and response on a given lock_owner must be cached as long as request and response on a given lock_owner must be cached as long as
the lock state exists on the server. the lock state exists on the server.
The client MUST monotonically increment the sequence number for the The client MUST monotonically increment the sequence number for the
CLOSE, LOCK, LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE CLOSE, LOCK, LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE
operations. This is true even in the event that the previous operations. This is true even in the event that the previous
operation that used the sequence number received an error. The only operation that used the sequence number received an error. The only
exception to this rule is if the previous operation received one of exception to this rule is if the previous operation received one of
skipping to change at page 117, line 5 skipping to change at page 117, line 21
storage would be required to guarantee ordered granting of blocking storage would be required to guarantee ordered granting of blocking
locks. locks.
Servers may also note the lock types and delay returning denial of Servers may also note the lock types and delay returning denial of
the request to allow extra time for a conflicting lock to be the request to allow extra time for a conflicting lock to be
released, allowing a successful return. In this way, clients can released, allowing a successful return. In this way, clients can
avoid the burden of needlessly frequent polling for blocking locks. avoid the burden of needlessly frequent polling for blocking locks.
The server should take care in the length of delay in the event the The server should take care in the length of delay in the event the
client retransmits the request. client retransmits the request.
If a server receives a blocking lock request, denies it, and then
later receives a nonblocking request for the same lock, which is also
denied, then it should remove the lock in question from its list of
pending blocking locks. Clients should use such a nonblocking
request to indicate to the server that this is the last time they
intend to poll for the lock, as may happen when the process
requesting the lock is interrupted. This is a courtesy to the
server, to prevent it from unnecessarily waiting a lease period
before granting other lock requests. However, clients are not
required to perform this courtesy, and servers must not depend on
them doing so. Also, clients must be prepared for the possibility
that this final locking request will be accepted.
9.5. Lease Renewal 9.5. Lease Renewal
The purpose of a lease is to allow a server to remove stale locks The purpose of a lease is to allow a server to remove stale locks
that are held by a client that has crashed or is otherwise that are held by a client that has crashed or is otherwise
unreachable. It is not a mechanism for cache consistency and lease unreachable. It is not a mechanism for cache consistency and lease
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, DELEGPURGE, o Any operation made with a valid stateid (CLOSE, DELEGPURGE,
DELEGRETURN, LOCK, LOCKU, OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE, DELEGRETURN, LOCK, LOCKU, OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE,
READ, RENEW, SETATTR, WRITE). This does not include the special READ, RENEW, SETATTR, or WRITE). This does not include the
stateids of all bits 0 or all bits 1. special stateids of all bits 0 or all bits 1.
Note that if the client had restarted or rebooted, the client Note that if the client had restarted or rebooted, the client
would not be making these requests without issuing the would not be making these requests without issuing the
SETCLIENTID/SETCLIENTID_CONFIRM sequence. The use of the SETCLIENTID/SETCLIENTID_CONFIRM sequence. The use of the
SETCLIENTID/SETCLIENTID_CONFIRM sequence (one that changes the SETCLIENTID/SETCLIENTID_CONFIRM sequence (one that changes the
client verifier) notifies the server to drop the locking state client verifier) notifies the server to drop the locking state
associated with the client. SETCLIENTID/SETCLIENTID_CONFIRM never associated with the client. SETCLIENTID/SETCLIENTID_CONFIRM never
renews a lease. renews a lease.
If the server has rebooted, the stateids (NFS4ERR_STALE_STATEID If the server has rebooted, the stateids (NFS4ERR_STALE_STATEID
skipping to change at page 120, line 15 skipping to change at page 120, line 46
subsequently reclaimed would have prevented any I/O operation subsequently reclaimed would have prevented any I/O operation
processed during the grace period. processed during the grace period.
Clients should be prepared for the return of NFS4ERR_GRACE errors for Clients should be prepared for the return of NFS4ERR_GRACE errors for
non-reclaim lock and I/O requests. In this case the client should non-reclaim lock and I/O requests. In this case the client should
employ a retry mechanism for the request. A delay (on the order of employ a retry mechanism for the request. A delay (on the order of
several seconds) between retries should be used to avoid overwhelming several seconds) between retries should be used to avoid overwhelming
the server. Further discussion of the general issue is included in the server. Further discussion of the general issue is included in
[20]. The client must account for the server that is able to perform [20]. The client must account for the server that is able to perform
I/O and non-reclaim locking requests within the grace period as well I/O and non-reclaim locking requests within the grace period as well
as those that can not do so. as those that cannot do so.
A reclaim-type locking request outside the server's grace period can A reclaim-type locking request outside the server's grace period can
only succeed if the server can guarantee that no conflicting lock or only succeed if the server can guarantee that no conflicting lock or
I/O request has been granted since reboot or restart. I/O request has been granted since reboot or restart.
A server may, upon restart, establish a new value for the lease A server may, upon restart, establish a new value for the lease
period. Therefore, clients should, once a new clientid is period. Therefore, clients should, once a new clientid is
established, refetch the lease_time attribute and use it as the basis established, refetch the lease_time attribute and use it as the basis
for lease renewal for the lease associated with that server. for lease renewal for the lease associated with that server.
However, the server must establish, for this restart event, a grace However, the server must establish, for this restart event, a grace
skipping to change at page 126, line 30 skipping to change at page 127, line 9
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;
9.10. OPEN/CLOSE Operations 9.10. 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 access, if any, to deny. Even if the client intends
use a stateid of all 0's or all 1's, it must still obtain the to 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.
The CLOSE operation removes all share reservations held by the The CLOSE operation removes all share reservations held by the
skipping to change at page 134, line 34 skipping to change at page 135, line 16
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.
On recall, the client holding the delegation must flush modified On recall, the client holding the delegation must flush modified
state (such as modified data) to the server and return the state (such as modified data) to the server and return the
delegation. The conflicting request will not receive a response delegation. The conflicting request will not be acted on until the
until the recall is complete. The recall is considered complete when recall is complete. The recall is considered complete when the
the client returns the delegation or the server times out on the client returns the delegation or the server times its wait for the
recall and revokes the delegation as a result of the timeout. delegation to be returned and revokes the delegation as a result of
the timeout. In the interim, the server will either delay responding
to conflicting requests or respond to them with NFS4ERR_DELAY.
Following the resolution of the recall, the server has the Following the resolution of the recall, the server has the
information necessary to grant or deny the second client's request. information necessary to grant or deny the second client's request.
At the time the client receives a delegation recall, it may have At the time the client receives a delegation recall, it may have
substantial state that needs to be flushed to the server. Therefore, substantial state that needs to be flushed to the server. Therefore,
the server should allow sufficient time for the delegation to be the server should allow sufficient time for the delegation to be
returned since it may involve numerous RPCs to the server. If the returned since it may involve numerous RPCs to the server. If the
server is able to determine that the client is diligently flushing server is able to determine that the client is diligently flushing
state to the server as a result of the recall, the server may extend state to the server as a result of the recall, the server may extend
the usual time allowed for a recall. However, the time allowed for the usual time allowed for a recall. However, the time allowed for
skipping to change at page 151, line 5 skipping to change at page 151, line 37
yet sent to the server, due to the delegation). The server yet sent to the server, due to the delegation). The server
SHOULD give the client a reasonable time to return its SHOULD give the client a reasonable time to return its
delegations to the server before revoking the client's delegations to the server before revoking the client's
delegations. delegations.
* The client has not issued a RENEW operation for some period of * The client has not issued a RENEW operation for some period of
time after the server attempted to recall the delegation. This time after the server attempted to recall the delegation. This
period of time MUST NOT be less than the value of the period of time MUST NOT be less than the value of the
lease_time attribute. lease_time attribute.
o When the client holds a delegation, it can not rely on operations, o When the client holds a delegation, it cannot rely on operations,
except for RENEW, that take a stateid, to renew delegation leases except for RENEW, that take a stateid, to renew delegation leases
across callback path failures. The client that wants to keep across callback path failures. The client that wants to keep
delegations in force across callback path failures must use RENEW delegations in force across callback path failures must use RENEW
to do so. to do so.
10.4.6. Delegation Revocation 10.4.6. Delegation Revocation
At the point a delegation is revoked, if there are associated opens At the point a delegation is revoked, if there are associated opens
on the client, the applications holding these opens need to be on the client, the applications holding these opens need to be
notified. This notification usually occurs by returning errors for notified. This notification usually occurs by returning errors for
skipping to change at page 189, line 25 skipping to change at page 190, line 25
procedure. The opcode in the result stream matched with this error procedure. The opcode in the result stream matched with this error
is the ILLEGAL value, although the value that appears in the request is the ILLEGAL value, although the value that appears in the request
stream may be different. Where an illegal value appears and the stream may be different. Where an illegal value appears and the
replier pre-parses all operations for a Compound procedure before replier pre-parses all operations for a Compound procedure before
doing any operation execution, an RPC-level XDR error may be returned doing any operation execution, an RPC-level XDR error may be returned
in this case. in this case.
13.1.3.4. NFS4ERR_RESOURCE (Error Code 10018) 13.1.3.4. NFS4ERR_RESOURCE (Error Code 10018)
For the processing of the Compound procedure, the server may exhaust For the processing of the Compound procedure, the server may exhaust
available resources and can not continue processing operations within available resources and cannot continue processing operations within
the Compound procedure. This error will be returned from the server the Compound procedure. This error will be returned from the server
in those instances of resource exhaustion related to the processing in those instances of resource exhaustion related to the processing
of the Compound procedure. of the Compound procedure.
13.1.4. File System Errors 13.1.4. File System Errors
These errors describe situations which occurred in the underlying These errors describe situations which occurred in the underlying
file system implementation rather than in the protocol or any NFSv4.x file system implementation rather than in the protocol or any NFSv4.x
feature. feature.
skipping to change at page 195, line 9 skipping to change at page 196, line 9
13.1.9.1. NFS4ERR_GRACE (Error Code 10013) 13.1.9.1. NFS4ERR_GRACE (Error Code 10013)
The server is in its recovery or grace period which should at least The server is in its recovery or grace period which should at least
match the lease period of the server. A locking request other than a match the lease period of the server. A locking request other than a
reclaim could not be granted during that period. reclaim could not be granted during that period.
13.1.9.2. NFS4ERR_NO_GRACE (Error Code 10033) 13.1.9.2. NFS4ERR_NO_GRACE (Error Code 10033)
A reclaim of client state was attempted in circumstances in which the A reclaim of client state was attempted in circumstances in which the
server cannot guarantee that conflicting state has not been provided server cannot guarantee that conflicting state has not been provided
to another client. As a result, the server can not guarantee that to another client. As a result, the server cannot guarantee that
conflicting state has not been provided to another client. conflicting state has not been provided to another client.
13.1.9.3. NFS4ERR_RECLAIM_BAD (Error Code 10034) 13.1.9.3. NFS4ERR_RECLAIM_BAD (Error Code 10034)
A reclaim attempted by the client does not match the server's state A reclaim attempted by the client does not match the server's state
consistency checks and has been rejected therefore as invalid. consistency checks and has been rejected therefore as invalid.
13.1.9.4. NFS4ERR_RECLAIM_CONFLICT (Error Code 10035) 13.1.9.4. NFS4ERR_RECLAIM_CONFLICT (Error Code 10035)
The reclaim attempted by the client has encountered a conflict and The reclaim attempted by the client has encountered a conflict and
skipping to change at page 216, line 24 skipping to change at page 217, line 24
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
15.3.5. IMPLEMENTATION 15.3.5. IMPLEMENTATION
In general, it is not sufficient for the client to attempt to deduce In general, it is not sufficient for the client to attempt to deduce
access permissions by inspecting the uid, gid, and mode fields in the access permissions by inspecting the uid, gid, and mode fields in the
file attributes or by attempting to interpret the contents of the ACL file attributes or by attempting to interpret the contents of the ACL
attribute. This is because the server may perform uid or gid mapping attribute. This is because the server may perform uid or gid mapping
or enforce additional access control restrictions. It is also or enforce additional access control restrictions. It is also
possible that the server may not be in the same ID space as the possible that the server may not be in the same ID space as the
client. In these cases (and perhaps others), the client can not client. In these cases (and perhaps others), the client cannot
reliably perform an access check with only current file attributes. reliably perform an access check with 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 operation in the NFS version 4 succeeded or failed. Using the ACCESS operation in the NFS version 4
protocol, the client can ask the server to indicate whether or not protocol, the client can ask the server to indicate whether or not
one or more classes of operations are permitted. The ACCESS one or more classes of operations are permitted. The ACCESS
operation is provided to allow clients to check before doing a series operation is provided to allow clients to check before doing a series
of operations which will result in an access failure. The OPEN of operations which will result in an access failure. The OPEN
operation provides a point where the server can verify access to the operation provides a point where the server can verify access to the
skipping to change at page 231, line 41 skipping to change at page 232, line 41
only LOCK for ranges that do not include any bytes already locked by only LOCK for ranges that do not include any bytes already locked by
that lock_owner and LOCKU of locks held by that lock_owner that lock_owner and LOCKU of locks held by that lock_owner
(specifying an exactly-matching range and type). Similarly, when the (specifying an exactly-matching range and type). Similarly, when the
client makes a lock request that amounts to upgrading (changing from client makes a lock request that amounts to upgrading (changing from
a read lock to a write lock) or downgrading (changing from write lock a read lock to a write lock) or downgrading (changing from write lock
to a read lock) an existing record lock, and the server does not to a read lock) an existing record lock, and the server does not
support such a lock, the server will return NFS4ERR_LOCK_NOTSUPP. support such a lock, the server will return NFS4ERR_LOCK_NOTSUPP.
Such operations may not perfectly reflect the required semantics in Such operations may not perfectly reflect the required semantics in
the face of conflicting lock requests from other clients. the face of conflicting lock requests from other clients.
The locker argument specifies the lock_owner that is associated with The locker argument specifies the lock-owner that is associated with
the LOCK request. The locker4 structure is a switched union that the LOCK request. The locker4 structure is a switched union that
indicates whether the lock_owner is known to the server or if the indicates whether the client has already created byte-range locking
lock_owner is new to the server. In the case that the lock_owner is state associated with the current open file and lock-owner. In the
known to the server and has an established lock_seqid, the argument case in which it has, the argument is just a stateid representing the
is just the lock_owner and lock_seqid. In the case that the set of locks associated with that open file and lock-owner, together
lock_owner is not known to the server, the argument contains not only with a lock_seqid value which MAY be any value and MUST be ignored by
the lock_owner and lock_seqid but also the open_stateid and the server. In the case where no byte-range locking state has been
open_seqid. The new lock_owner case covers the very first lock done established, or the client does not have the stateid available, the
by the lock_owner and offers a method to use the established state of argument contains the stateid of the open file with which this lock
the open_stateid to transition to the use of the lock_owner. is to be associated, together with the lock-owner with which the lock
is to be associated. The open_to_lock_owner case covers the very
first lock done by a lock-owner for a given open file and offers a
method to use the established state of the open_stateid to transition
to the use of a lock stateid.
The following fields of the locker parameter MAY be set to any value
by the client and MUST be ignored by the server:
o The clientid field of the lock_owner field of the open_owner field
(locker.open_owner.lock_owner.clientid). The reason the server
MUST ignore the clientid field is that the server MUST derive the
client ID from the session ID from the SEQUENCE operation of the
COMPOUND request.
o The open_seqid and lock_seqid fields of the open_owner field
(locker.open_owner.open_seqid and locker.open_owner.lock_seqid).
o The lock_seqid field of the lock_owner field
(locker.lock_owner.lock_seqid).
15.13. Operation 13: LOCKT - Test For Lock 15.13. Operation 13: LOCKT - Test For Lock
15.13.1. SYNOPSIS 15.13.1. SYNOPSIS
(cfh) locktype, offset, length owner -> {void, NFS4ERR_DENIED -> (cfh) locktype, offset, length, owner -> {void, NFS4ERR_DENIED ->
owner} owner}
15.13.2. ARGUMENT 15.13.2. ARGUMENT
struct LOCKT4args { struct LOCKT4args {
/* CURRENT_FH: file */ /* CURRENT_FH: file */
nfs_lock_type4 locktype; nfs_lock_type4 locktype;
offset4 offset; offset4 offset;
length4 length; length4 length;
lock_owner4 owner; lock_owner4 owner;
skipping to change at page 238, line 20 skipping to change at page 239, line 41
When the attribute rdattr_error or any write-only attribute (e.g., When the attribute rdattr_error or any write-only attribute (e.g.,
time_modify_set) is specified, the error NFS4ERR_INVAL is returned to time_modify_set) is specified, the error NFS4ERR_INVAL is returned to
the client. the client.
15.18. Operation 18: OPEN - Open a Regular File 15.18. Operation 18: OPEN - Open a Regular File
15.18.1. SYNOPSIS 15.18.1. SYNOPSIS
(cfh), seqid, share_access, share_deny, owner, openhow, claim -> (cfh), seqid, share_access, share_deny, owner, openhow, claim ->
(cfh), stateid, cinfo, rflags, open_confirm, attrset delegation (cfh), stateid, cinfo, rflags, attrset, delegation
15.18.2. ARGUMENT 15.18.2. ARGUMENT
/* /*
* Various definitions for OPEN * Various definitions for OPEN
*/ */
enum createmode4 { enum createmode4 {
UNCHECKED4 = 0, UNCHECKED4 = 0,
GUARDED4 = 1, GUARDED4 = 1,
EXCLUSIVE4 = 2 EXCLUSIVE4 = 2
skipping to change at page 245, line 11 skipping to change at page 246, line 32
OPEN_CONFIRM operation before using the open file. OPEN_CONFIRM operation before using the open file.
OPEN4_RESULT_LOCKTYPE_POSIX indicates the server's file locking OPEN4_RESULT_LOCKTYPE_POSIX indicates the server's file locking
behavior supports the complete set of Posix locking techniques. From behavior supports the complete set of Posix locking techniques. From
this the client can choose to manage file locking state in a way to this the client can choose to manage file locking state in a way to
handle a mis-match of file locking management. handle a mis-match of file locking management.
If the component is of zero length, NFS4ERR_INVAL will be returned. If the component is of zero length, NFS4ERR_INVAL will be returned.
The component is also subject to the normal UTF-8, character support, The component is also subject to the normal UTF-8, character support,
and name checks. See Section 12.3 for further discussion. and name checks. See Section 12.3 for further discussion.
When an OPEN is done and the specified lockowner already has the When an OPEN is done and the specified open_owner already has the
resulting filehandle open, the result is to "OR" together the new resulting filehandle open, the result is to "OR" together the new
share and deny status together with the existing status. In this share and deny status together with the existing status. In this
case, only a single CLOSE need be done, even though multiple OPENs case, only a single CLOSE need be done, even though multiple OPENs
were completed. When such an OPEN is done, checking of share were completed. When such an OPEN is done, checking of share
reservations for the new OPEN proceeds normally, with no exception reservations for the new OPEN proceeds normally, with no exception
for the existing OPEN held by the same lockowner. for the existing OPEN held by the same owner.
If the underlying filesystem at the server is only accessible in a If the underlying filesystem at the server is only accessible in a
read-only mode and the OPEN request has specified ACCESS_WRITE or read-only mode and the OPEN request has specified ACCESS_WRITE or
ACCESS_BOTH, the server will return NFS4ERR_ROFS to indicate a read- ACCESS_BOTH, the server will return NFS4ERR_ROFS to indicate a read-
only filesystem. only filesystem.
As with the CREATE operation, the server MUST derive the owner, owner As with the CREATE operation, the server MUST derive the owner, owner
ACE, group, or group ACE if any of the four attributes are required ACE, group, or group ACE if any of the four attributes are required
and supported by the server's filesystem. For an OPEN with the and supported by the server's filesystem. For an OPEN with the
EXCLUSIVE4 createmode, the server has no choice, since such OPEN EXCLUSIVE4 createmode, the server has no choice, since such OPEN
skipping to change at page 246, line 19 skipping to change at page 247, line 40
usage, exclusive CREATE does not rely solely on the normally volatile usage, exclusive CREATE does not rely solely on the normally volatile
duplicate request cache for storage of the verifier. The duplicate duplicate request cache for storage of the verifier. The duplicate
request cache in volatile storage does not survive a crash and may request cache in volatile storage does not survive a crash and may
actually flush on a long network partition, opening failure windows. actually flush on a long network partition, opening failure windows.
In the UNIX local filesystem environment, the expected storage In the UNIX local filesystem environment, the expected storage
location for the verifier on creation is the meta-data (time stamps) location for the verifier on creation is the meta-data (time stamps)
of the object. For this reason, an exclusive object create may not of the object. For this reason, an exclusive object create may not
include initial attributes because the server would have nowhere to include initial attributes because the server would have nowhere to
store the verifier. store the verifier.
If the server can not support these exclusive create semantics, If the server cannot support these exclusive create semantics,
possibly because of the requirement to commit the verifier to stable possibly because of the requirement to commit the verifier to stable
storage, it should fail the OPEN request with the error, storage, it should fail the OPEN request with the error,
NFS4ERR_NOTSUPP. NFS4ERR_NOTSUPP.
During an exclusive CREATE request, if the object already exists, the During an exclusive CREATE request, if the object already exists, the
server reconstructs the object's verifier and compares it with the server reconstructs the object's verifier and compares it with the
verifier in the request. If they match, the server treats the verifier in the request. If they match, the server treats the
request as a success. The request is presumed to be a duplicate of request as a success. The request is presumed to be a duplicate of
an earlier, successful request for which the reply was lost and that an earlier, successful request for which the reply was lost and that
the server duplicate request cache mechanism did not detect. If the the server duplicate request cache mechanism did not detect. If the
skipping to change at page 249, line 25 skipping to change at page 250, line 39
void; void;
}; };
15.20.4. DESCRIPTION 15.20.4. DESCRIPTION
This operation is used to confirm the sequence id usage for the first This operation is used to confirm the sequence id usage for the first
time that a open_owner is used by a client. The stateid returned time that a open_owner is used by a client. The stateid returned
from the OPEN operation is used as the argument for this operation from the OPEN operation is used as the argument for this operation
along with the next sequence id for the open_owner. The sequence id along with the next sequence id for the open_owner. The sequence id
passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid passed to the OPEN_CONFIRM must be 1 (one) greater than the seqid
passed to the OPEN operation from which the open_confirm value was passed to the OPEN operation. If the server receives an unexpected
obtained. If the server receives an unexpected sequence id with sequence id with respect to the original open, then the server
respect to the original open, then the server assumes that the client assumes that the client will not confirm the original OPEN and all
will not confirm the original OPEN and all state associated with the state associated with the original OPEN is released by the server.
original OPEN is released by the server.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
15.20.5. IMPLEMENTATION 15.20.5. IMPLEMENTATION
A given client might generate many open_owner4 data structures for a A given client might generate many open_owner4 data structures for a
given clientid. The client will periodically either dispose of its given clientid. The client will periodically either dispose of its
open_owner4s or stop using them for indefinite periods of time. The open_owner4s or stop using them for indefinite periods of time. The
latter situation is why the NFS version 4 protocol does not have an latter situation is why the NFS version 4 protocol does not have an
explicit operation to exit an open_owner4: such an operation is of no explicit operation to exit an open_owner4: such an operation is of no
use in that situation. Instead, to avoid unbounded memory use, the use in that situation. Instead, to avoid unbounded memory use, the
server needs to implement a strategy for disposing of open_owner4s server needs to implement a strategy for disposing of open_owner4s
that have no current lock, open, or delegation state for any files that have no current open state for any files and have not been used
and have not been used recently. The time period used to determine recently. The time period used to determine when to dispose of
when to dispose of open_owner4s is an implementation choice. The open_owner4s is an implementation choice. The time period should
time period should certainly be no less than the lease time plus any certainly be no less than the lease time plus any grace period the
grace period the server wishes to implement beyond a lease time. The server wishes to implement beyond a lease time. The OPEN_CONFIRM
OPEN_CONFIRM operation allows the server to safely dispose of unused operation allows the server to safely dispose of unused open_owner4
open_owner4 data structures. data structures.
In the case that a client issues an OPEN operation and the server no In the case that a client issues an OPEN operation and the server no
longer has a record of the open_owner4, the server needs to ensure longer has a record of the open_owner4, the server needs to ensure
that this is a new OPEN and not a replay or retransmission. that this is a new OPEN and not a replay or retransmission.
Servers must not require confirmation on OPENs that grant delegations Servers must not require confirmation on OPENs that grant delegations
or are doing reclaim operations. See Section 9.1.8 for details. The or are doing reclaim operations. See Section 9.1.8 for details. The
server can easily avoid this by noting whether it has disposed of one server can easily avoid this by noting whether it has disposed of one
open_owner4 for the given clientid. If the server does not support open_owner4 for the given clientid. If the server does not support
delegation, it might simply maintain a single bit that notes whether delegation, it might simply maintain a single bit that notes whether
skipping to change at page 253, line 20 skipping to change at page 254, line 24
}; };
15.23.4. DESCRIPTION 15.23.4. DESCRIPTION
Replaces the current filehandle with the filehandle that represents Replaces the current filehandle with the filehandle that represents
the public filehandle of the server's name space. This filehandle the public filehandle of the server's name space. This filehandle
may be different from the "root" filehandle which may be associated may be different from the "root" filehandle which may be associated
with some other directory on the server. with some other directory on the server.
The public filehandle represents the concepts embodied in [23], [24], The public filehandle represents the concepts embodied in [23], [24],
[31]. The intent for NFS version 4 is that the public filehandle [35]. The intent for NFS version 4 is that the public filehandle
(represented by the PUTPUBFH operation) be used as a method of (represented by the PUTPUBFH operation) be used as a method of
providing WebNFS server compatibility with NFS versions 2 and 3. providing WebNFS server compatibility with NFS versions 2 and 3.
The public filehandle and the root filehandle (represented by the The public filehandle and the root filehandle (represented by the
PUTROOTFH operation) should be equivalent. If the public and root PUTROOTFH operation) should be equivalent. If the public and root
filehandles are not equivalent, then the public filehandle MUST be a filehandles are not equivalent, then the public filehandle MUST be a
descendant of the root filehandle. descendant of the root filehandle.
15.23.5. IMPLEMENTATION 15.23.5. IMPLEMENTATION
Used as the first operator in an NFS request to set the context for Used as the first operator in an NFS request to set the context for
following operations. following operations.
With the NFS version 2 and 3 public filehandle, the client is able to With the NFS version 2 and 3 public filehandle, the client is able to
specify whether the path name provided in the LOOKUP should be specify whether the path name provided in the LOOKUP should be
evaluated as either an absolute path relative to the server's root or evaluated as either an absolute path relative to the server's root or
relative to the public filehandle. [31] contains further discussion relative to the public filehandle. [35] contains further discussion
of the functionality. With NFS version 4, that type of specification of the functionality. With NFS version 4, that type of specification
is not directly available in the LOOKUP operation. The reason for is not directly available in the LOOKUP operation. The reason for
this is because the component separators needed to specify absolute this is because the component separators needed to specify absolute
vs. relative are not allowed in NFS version 4. Therefore, the client vs. relative are not allowed in NFS version 4. Therefore, the client
is responsible for constructing its request such that the use of is responsible for constructing its request such that the use of
either PUTROOTFH or PUTPUBFH are used to signify absolute or relative either PUTROOTFH or PUTPUBFH are used to signify absolute or relative
evaluation of an NFS URL respectively. evaluation of an NFS URL respectively.
Note that there are warnings mentioned in [31] with respect to the Note that there are warnings mentioned in [35] with respect to the
use of absolute evaluation and the restrictions the server may place use of absolute evaluation and the restrictions the server may place
on that evaluation with respect to how much of its namespace has been on that evaluation with respect to how much of its namespace has been
made available. These same warnings apply to NFS version 4. It is made available. These same warnings apply to NFS version 4. It is
likely, therefore that because of server implementation details, an likely, therefore that because of server implementation details, an
NFS version 3 absolute public filehandle lookup may behave NFS version 3 absolute public filehandle lookup may behave
differently than an NFS version 4 absolute resolution. differently than an NFS version 4 absolute resolution.
There is a form of security negotiation as described in [32] that There is a form of security negotiation as described in [36] that
uses the public filehandle a method of employing SNEGO. This method uses the public filehandle a method of employing SNEGO. This method
is not available with NFS version 4 as filehandles are not overloaded is not available with NFS version 4 as filehandles are not overloaded
with special meaning and therefore do not provide the same framework with special meaning and therefore do not provide the same framework
as NFS versions 2 and 3. Clients should therefore use the security as NFS versions 2 and 3. Clients should therefore use the security
negotiation mechanisms described in this RFC. negotiation mechanisms described in this RFC.
15.24. Operation 24: PUTROOTFH - Set Root Filehandle 15.24. Operation 24: PUTROOTFH - Set Root Filehandle
15.24.1. SYNOPSIS 15.24.1. SYNOPSIS
skipping to change at page 269, line 41 skipping to change at page 271, line 33
The SECINFO operation is expected to be used by the NFS client when The SECINFO operation is expected to be used by the NFS client when
the error value of NFS4ERR_WRONGSEC is returned from another NFS the error value of NFS4ERR_WRONGSEC is returned from another NFS
operation. This signifies to the client that the server's security operation. This signifies to the client that the server's security
policy is different from what the client is currently using. At this policy is different from what the client is currently using. At this
point, the client is expected to obtain a list of possible security point, the client is expected to obtain a list of possible security
flavors and choose what best suits its policies. flavors and choose what best suits its policies.
As mentioned, the server's security policies will determine when a As mentioned, the server's security policies will determine when a
client request receives NFS4ERR_WRONGSEC. The operations which may client request receives NFS4ERR_WRONGSEC. The operations which may
receive this error are: LINK, LOOKUP, OPEN, PUTFH, PUTPUBFH, receive this error are: LINK, LOOKUP, LOOKUPP, OPEN, PUTFH, PUTPUBFH,
PUTROOTFH, RESTOREFH, RENAME, and indirectly READDIR. LINK and PUTROOTFH, RENAME, RESTOREFH, and indirectly READDIR. LINK and
RENAME will only receive this error if the security used for the RENAME will only receive this error if the security used for the
operation is inappropriate for saved filehandle. With the exception operation is inappropriate for saved filehandle. With the exception
of READDIR, these operations represent the point at which the client of READDIR, these operations represent the point at which the client
can instantiate a filehandle into the "current filehandle" at the can instantiate a filehandle into the "current filehandle" at the
server. The filehandle is either provided by the client (PUTFH, server. The filehandle is either provided by the client (PUTFH,
PUTPUBFH, PUTROOTFH) or generated as a result of a name to filehandle PUTPUBFH, PUTROOTFH) or generated as a result of a name to filehandle
translation (LOOKUP and OPEN). RESTOREFH is different because the translation (LOOKUP and OPEN). RESTOREFH is different because the
filehandle is a result of a previous SAVEFH. Even though the filehandle is a result of a previous SAVEFH. Even though the
filehandle, for RESTOREFH, might have previously passed the server's filehandle, for RESTOREFH, might have previously passed the server's
inspection for a security match, the server will check it again on inspection for a security match, the server will check it again on
skipping to change at page 270, line 19 skipping to change at page 272, line 11
o For LOOKUP and OPEN, the client will use SECINFO with the same o For LOOKUP and OPEN, the client will use SECINFO with the same
current filehandle and name as provided in the original LOOKUP or current filehandle and name as provided in the original LOOKUP or
OPEN to enumerate the available security triples. OPEN to enumerate the available security triples.
o For LINK, PUTFH, RENAME, and RESTOREFH, the client will use o For LINK, PUTFH, RENAME, and RESTOREFH, the client will use
SECINFO and provide the parent directory filehandle and object SECINFO and provide the parent directory filehandle and object
name which corresponds to the filehandle originally provided by name which corresponds to the filehandle originally provided by
the PUTFH RESTOREFH, or for LINK and RENAME, the SAVEFH. the PUTFH RESTOREFH, or for LINK and RENAME, the SAVEFH.
o For PUTROOTFH and PUTPUBFH, the client will be unable to use the o For LOOKUPP, PUTROOTFH and PUTPUBFH, the client will be unable to
SECINFO operation since SECINFO requires a current filehandle and use the SECINFO operation since SECINFO requires a current
none exist for these two operations. Therefore, the client must filehandle and none exist for these two operations. Therefore,
iterate through the security triples available at the client and the client must iterate through the security triples available at
reattempt the PUTROOTFH or PUTPUBFH operation. In the unfortunate the client and reattempt the PUTROOTFH or PUTPUBFH operation. In
event none of the MANDATORY security triples are supported by the the unfortunate event none of the MANDATORY security triples are
client and server, the client SHOULD try using others that support supported by the client and server, the client SHOULD try using
integrity. Failing that, the client can try using AUTH_NONE, but others that support integrity. Failing that, the client can try
because such forms lack integrity checks, this puts the client at using AUTH_NONE, but because such forms lack integrity checks,
risk. Nonetheless, the server SHOULD allow the client to use this puts the client at risk. Nonetheless, the server SHOULD
whatever security form the client requests and the server allow the client to use whatever security form the client requests
supports, since the risks of doing so are on the client. and the server supports, since the risks of doing so are on the
client.
The READDIR operation will not directly return the NFS4ERR_WRONGSEC The READDIR operation will not directly return the NFS4ERR_WRONGSEC
error. However, if the READDIR request included a request for error. However, if the READDIR request included a request for
attributes, it is possible that the READDIR request's security triple attributes, it is possible that the READDIR request's security triple
does not match that of a directory entry. If this is the case and does not match that of a directory entry. If this is the case and
the client has requested the rdattr_error attribute, the server will the client has requested the rdattr_error attribute, the server will
return the NFS4ERR_WRONGSEC error in rdattr_error for the entry. return the NFS4ERR_WRONGSEC error in rdattr_error for the entry.
See Section 17 for a discussion on the recommendations for security See Section 17 for a discussion on the recommendations for security
flavor used by SECINFO. flavor used by SECINFO.
skipping to change at page 297, line 28 skipping to change at page 299, line 28
[22] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)", [22] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)",
RFC 2025, October 1996. RFC 2025, October 1996.
[23] Callaghan, B., "WebNFS Client Specification", RFC 2054, [23] Callaghan, B., "WebNFS Client Specification", RFC 2054,
October 1996. October 1996.
[24] Callaghan, B., "WebNFS Server Specification", RFC 2055, [24] Callaghan, B., "WebNFS Server Specification", RFC 2055,
October 1996. October 1996.
[25] Shepler, S., "NFS Version 4 Design Considerations", RFC 2624, [25] IESG, "IESG Processing of RFC Errata for the IETF Stream",
July 2008.
[26] The Open Group, "Section 'read()' of System Interfaces of The
Open Group Base Specifications Issue 6, IEEE Std 1003.1, 2004
Edition", 2004.
[27] The Open Group, "Section 'readdir()' of System Interfaces of
The Open Group Base Specifications Issue 6, IEEE Std 1003.1,
2004 Edition", 2004.
[28] The Open Group, "Section 'write()' of System Interfaces of The
Open Group Base Specifications Issue 6, IEEE Std 1003.1, 2004
Edition", 2004.
[29] Shepler, S., "NFS Version 4 Design Considerations", RFC 2624,
June 1999. June 1999.
[26] Simonsen, K., "Character Mnemonics and Character Sets", [30] Simonsen, K., "Character Mnemonics and Character Sets",
RFC 1345, June 1992. RFC 1345, June 1992.
[27] Shepler, S., Eisler, M., and D. Noveck, "Network File System [31] Shepler, S., Eisler, M., and D. Noveck, "Network File System
(NFS) Version 4 Minor Version 1 Protocol", RFC 5661, (NFS) Version 4 Minor Version 1 Protocol", RFC 5661,
January 2010. January 2010.
[28] The Open Group, "Protocols for Interworking: XNFS, Version 3W, [32] The Open Group, "Protocols for Interworking: XNFS, Version 3W,
ISBN 1-85912-184-5", February 1998. ISBN 1-85912-184-5", February 1998.
[29] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, [33] Postel, J., "Transmission Control Protocol", STD 7, RFC 793,
September 1981. September 1981.
[30] Juszczak, C., "Improving the Performance and Correctness of an [34] Juszczak, C., "Improving the Performance and Correctness of an
NFS Server", USENIX Conference Proceedings , June 1990. NFS Server", USENIX Conference Proceedings , June 1990.
[31] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997. [35] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997.
[32] Chiu, A., Eisler, M., and B. Callaghan, "Security Negotiation [36] Chiu, A., Eisler, M., and B. Callaghan, "Security Negotiation
for WebNFS", RFC 2755, January 2000. for WebNFS", RFC 2755, January 2000.
[33] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA [37] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. Considerations Section in RFCs", BCP 26, RFC 5226, May 2008.
Appendix A. Acknowledgments Appendix A. Acknowledgments
Rob Thurlow clarified how a client should contact a new server if a Rob Thurlow clarified how a client should contact a new server if a
migration has occured. migration has occured.
David Black, Nico Williams, Mike Eisler, Trond Myklebust, and James David Black, Nico Williams, Mike Eisler, Trond Myklebust, and James
Lentini read many drafts of Section 12 and contributed numerous Lentini read many drafts of Section 12 and contributed numerous
useful suggestions, without which the necessary revision of that useful suggestions, without which the necessary revision of that
 End of changes. 164 change blocks. 
374 lines changed or deleted 434 lines changed or added

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