draft-ietf-nfsv4-rfc3530bis-04.txt   draft-ietf-nfsv4-rfc3530bis-05.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: January 8, 2011 July 07, 2010 Expires: April 24, 2011 October 21, 2010
NFS Version 4 Protocol NFS Version 4 Protocol
draft-ietf-nfsv4-rfc3530bis-04.txt draft-ietf-nfsv4-rfc3530bis-05.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 January 8, 2011. This Internet-Draft will expire on April 24, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 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
skipping to change at page 4, line 27 skipping to change at page 4, line 27
6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 70 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 70
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 . . . . . . . . . . . . . . . . 72
7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 74 7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 74
7.1. Location Attributes . . . . . . . . . . . . . . . . . . 74 7.1. Location Attributes . . . . . . . . . . . . . . . . . . 74
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 . . . . . . . . . . . . . . 78 7.4. Uses of Location Information . . . . . . . . . . . . . . 77
7.4.1. File System Replication . . . . . . . . . . . . . . 78 7.4.1. File System Replication . . . . . . . . . . . . . . 78
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 . . . . . . . . . . 80
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 . . 83
7.7.2. Filehandles and File System Transitions . . . . . . 83 7.7.2. Filehandles and File System Transitions . . . . . . 83
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 . . . . . . . . . 85
7.7.5. The Change Attribute and File System Transitions . . 85 7.7.5. The Change Attribute and File System Transitions . . 85
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 . . . . . . . . . . . . . . . . . . . . 88
7.7.9. File System Data and File System Transitions . . . . 88 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) . . . . . . . . . . . . . 90
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 . . . . . . . . . . . . . 98
8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 99 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 . . . . . . . . . . . . . . . . 100
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 . . . . . . . . . . . . . . . . . . . . . 101
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 . . . . . . 102
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 . . . . . . . . . 107 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 . . . . . . . . . . . . 111
9.1.6. Recovery from Replayed Requests . . . . . . . . . . 112 9.1.6. Recovery from Replayed Requests . . . . . . . . . . 112
9.1.7. Releasing lock_owner State . . . . . . . . . . . . . 112 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 . . . . . . . . . . . . 114 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 115
9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 115 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 115
9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 115 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 116
9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 116 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 116
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 . . . . . . . . . . . . 117
9.6.3. Network Partitions and Recovery . . . . . . . . . . 119 9.6.3. Network Partitions and Recovery . . . . . . . . . . 119
9.7. Recovery from a Lock Request Timeout or Abort . . . . . 122 9.7. Recovery from a Lock Request Timeout or Abort . . . . . 123
9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 123 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 123
9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 124 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 124
9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 125 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 125
9.10.1. Close and Retention of State Information . . . . . . 125 9.10.1. Close and Retention of State Information . . . . . . 126
9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 126 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 126
9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 127 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 127
9.13. Clocks, Propagation Delay, and Calculating Lease 9.13. Clocks, Propagation Delay, and Calculating Lease
Expiration . . . . . . . . . . . . . . . . . . . . . . . 127 Expiration . . . . . . . . . . . . . . . . . . . . . . . 127
9.14. Migration, Replication and State . . . . . . . . . . . . 128 9.14. Migration, Replication and State . . . . . . . . . . . . 128
9.14.1. Migration and State . . . . . . . . . . . . . . . . 128 9.14.1. Migration and State . . . . . . . . . . . . . . . . 128
9.14.2. Replication and State . . . . . . . . . . . . . . . 129 9.14.2. Replication and State . . . . . . . . . . . . . . . 129
9.14.3. Notification of Migrated Lease . . . . . . . . . . . 129 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 . . . . . . . 130
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 . . . . . 131
10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 132 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 132
10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 133 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 134
10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 135 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 136
10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 136 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 136
10.3.2. Data Caching and File Locking . . . . . . . . . . . 137 10.3.2. Data Caching and File Locking . . . . . . . . . . . 137
10.3.3. Data Caching and Mandatory File Locking . . . . . . 138 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 . . . . . . . . . . . 139
10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 140 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 140
10.4.1. Open Delegation and Data Caching . . . . . . . . . . 142 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 142
10.4.2. Open Delegation and File Locks . . . . . . . . . . . 143 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 144
10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 144 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 144
10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 147 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 147
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 . . . . . . . . . . . . . . . 149 10.4.6. Delegation Revocation . . . . . . . . . . . . . . . 150
10.5. Data Caching and Revocation . . . . . . . . . . . . . . 150 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 150
10.5.1. Revocation Recovery for Write Open Delegation . . . 150 10.5.1. Revocation Recovery for Write Open Delegation . . . 151
10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 151 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 151
10.7. Data and Metadata Caching and Memory Mapped Files . . . 153 10.7. Data and Metadata Caching and Memory Mapped Files . . . 153
10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 155 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 156
10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 156 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 157
11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 157 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 157
12. Internationalization . . . . . . . . . . . . . . . . . . . . 160 12. Internationalization . . . . . . . . . . . . . . . . . . . . 160
12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 161 12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 161
12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 161 12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 161
12.1.2. Normalization, Equivalence, and Confusability . . . 162 12.1.2. Normalization, Equivalence, and Confusability . . . 162
12.2. String Type Overview . . . . . . . . . . . . . . . . . . 164 12.2. String Type Overview . . . . . . . . . . . . . . . . . . 165
12.2.1. Overall String Class Divisions . . . . . . . . . . . 164 12.2.1. Overall String Class Divisions . . . . . . . . . . . 165
12.2.2. Divisions by Typedef Parent types . . . . . . . . . 165 12.2.2. Divisions by Typedef Parent types . . . . . . . . . 166
12.2.3. Individual Types and Their Handling . . . . . . . . 166 12.2.3. Individual Types and Their Handling . . . . . . . . 167
12.3. Errors Related to Strings . . . . . . . . . . . . . . . 167 12.3. Errors Related to Strings . . . . . . . . . . . . . . . 168
12.4. Types with Pre-processing to Resolve Mixture Issues . . 168 12.4. Types with Pre-processing to Resolve Mixture Issues . . 169
12.4.1. Processing of Principal Strings . . . . . . . . . . 168 12.4.1. Processing of Principal Strings . . . . . . . . . . 169
12.4.2. Processing of Server Id Strings . . . . . . . . . . 168 12.4.2. Processing of Server Id Strings . . . . . . . . . . 169
12.5. String Types without Internationalization Processing . . 169 12.5. String Types without Internationalization Processing . . 170
12.6. Types with Processing Defined by Other Internet Areas . 169 12.6. Types with Processing Defined by Other Internet Areas . 170
12.7. String Types with NFS-specific Processing . . . . . . . 170 12.7. String Types with NFS-specific Processing . . . . . . . 171
12.7.1. Handling of File Came Components . . . . . . . . . . 171 12.7.1. Handling of File Name Components . . . . . . . . . . 172
12.7.2. Processing of Link Text . . . . . . . . . . . . . . 178 12.7.2. Processing of Link Text . . . . . . . . . . . . . . 181
12.7.3. Processing of Principal Prefixes . . . . . . . . . . 179 12.7.3. Processing of Principal Prefixes . . . . . . . . . . 182
13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 179 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 183
13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 180 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 183
13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 181 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 185
13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 183 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 186
13.1.3. Compound Structure Errors . . . . . . . . . . . . . 184 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 187
13.1.4. File System Errors . . . . . . . . . . . . . . . . . 185 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 188
13.1.5. State Management Errors . . . . . . . . . . . . . . 187 13.1.5. State Management Errors . . . . . . . . . . . . . . 190
13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 188 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 191
13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 188 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 191
13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 189 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 192
13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 190 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 193
13.1.10. Client Management Errors . . . . . . . . . . . . . . 191 13.1.10. Client Management Errors . . . . . . . . . . . . . . 194
13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 191 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 194
13.2. Operations and their valid errors . . . . . . . . . . . 192 13.2. Operations and their valid errors . . . . . . . . . . . 195
13.3. Callback operations and their valid errors . . . . . . . 199 13.3. Callback operations and their valid errors . . . . . . . 203
13.4. Errors and the operations that use them . . . . . . . . 199 13.4. Errors and the operations that use them . . . . . . . . 203
14. NFS version 4 Requests . . . . . . . . . . . . . . . . . . . 204 14. NFS version 4 Requests . . . . . . . . . . . . . . . . . . . 207
14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 204 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 208
14.2. Evaluation of a Compound Request . . . . . . . . . . . . 205 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 208
14.3. Synchronous Modifying Operations . . . . . . . . . . . . 206 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 209
14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 206 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 210
15. NFS version 4 Procedures . . . . . . . . . . . . . . . . . . 206 15. NFS version 4 Procedures . . . . . . . . . . . . . . . . . . 210
15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 206 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 210
15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 207 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 210
15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 209 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 213
15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 212 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 216
15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 213 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 217
15.6. Operation 6: CREATE - Create a Non-Regular File Object . 216 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 219
15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 218 Recovery . . . . . . . . . . . . . . . . . . . . . . . . 222
15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 219 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 223
15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 220 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 223
15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 221 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 224
15.11. Operation 11: LINK - Create Link to a File . . . . . . . 222 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 225
15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 224 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 227
15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 228 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 231
15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 229 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 232
15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 230 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 233
15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 232 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 235
15.17. Operation 17: NVERIFY - Verify Difference in 15.17. Operation 17: NVERIFY - Verify Difference in
Attributes . . . . . . . . . . . . . . . . . . . . . . . 233 Attributes . . . . . . . . . . . . . . . . . . . . . . . 236
15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 234 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 237
15.19. Operation 19: OPENATTR - Open Named Attribute 15.19. Operation 19: OPENATTR - Open Named Attribute
Directory . . . . . . . . . . . . . . . . . . . . . . . 243 Directory . . . . . . . . . . . . . . . . . . . . . . . 246
15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 244 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 247
15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 246 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 249
15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 248 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 251
15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 248 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 251
15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 250 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 253
15.25. Operation 25: READ - Read from File . . . . . . . . . . 250 15.25. Operation 25: READ - Read from File . . . . . . . . . . 253
15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 252 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 255
15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 256 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 259
15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 257 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 260
15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 259 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 262
15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 261 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 264
15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 262 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 265
15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 263 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 266
15.33. Operation 33: SECINFO - Obtain Available Security . . . 263 15.33. Operation 33: SECINFO - Obtain Available Security . . . 266
15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 266 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 269
15.35. Operation 35: SETCLIENTID - Negotiate Clientid . . . . . 269 15.35. Operation 35: SETCLIENTID - Negotiate Clientid . . . . . 272
15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid . . 272 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid . . 275
15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 276 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 279
15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 277 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 280
15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner
State . . . . . . . . . . . . . . . . . . . . . . . . . 281 State . . . . . . . . . . . . . . . . . . . . . . . . . 284
15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 282 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 285
16. NFS version 4 Callback Procedures . . . . . . . . . . . . . . 283 16. NFS version 4 Callback Procedures . . . . . . . . . . . . . . 286
16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 283 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 286
16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 284 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 287
16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 285 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 288
16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 286 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 289
16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback
Operation . . . . . . . . . . . . . . . . . . . . . 287 Operation . . . . . . . . . . . . . . . . . . . . . 290
17. Security Considerations . . . . . . . . . . . . . . . . . . . 288 17. Security Considerations . . . . . . . . . . . . . . . . . . . 291
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 290 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 293
18.1. Named Attribute Definition . . . . . . . . . . . . . . . 290 18.1. Named Attribute Definition . . . . . . . . . . . . . . . 293
18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 290 18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 293
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 291 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 294
19.1. Normative References . . . . . . . . . . . . . . . . . . 291 19.1. Normative References . . . . . . . . . . . . . . . . . . 294
19.2. Informative References . . . . . . . . . . . . . . . . . 292 19.2. Informative References . . . . . . . . . . . . . . . . . 295
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 294 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 297
Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 294 Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 297
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 294 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 297
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 9, line 37 skipping to change at page 9, line 37
o More liberal handling of internationalization for file names and o More liberal handling of internationalization for file names and
user and group names, with the elimination of restrictions imposed user and group names, with the elimination of restrictions imposed
by stringprep, with the recognition that rules for the forms of by stringprep, with the recognition that rules for the forms of
these name are the province of the receiving entity. these name are the province of the receiving entity.
o Updating handling of domain names to reflect IDNA. o Updating handling of domain names to reflect IDNA.
o Restructuring of string types to more appropriately reflect the o Restructuring of string types to more appropriately reflect the
reality of required string processing. reality of required string processing.
o LIPKEY SPKM/3 has been moved from being mandatory to optional o LIPKEY SPKM/3 has been moved from being REQUIRED to OPTIONAL.
o Some clarification on a client re-establishing callback o Some clarification on a client re-establishing callback
information to the new server if state has been migrated information to the new server if state has been migrated
1.2. Changes since RFC 3010 1.2. Changes since RFC 3010
This definition of the NFS version 4 protocol replaces or obsoletes This definition of the NFS version 4 protocol replaces or obsoletes
the definition present in [12]. While portions of the two documents the definition present in [12]. While portions of the two documents
have remained the same, there have been substantive changes in have remained the same, there have been substantive changes in
others. The changes made between [12] and this document represent others. The changes made between [12] and this document represent
skipping to change at page 21, line 28 skipping to change at page 21, line 28
uint64_t major; uint64_t major;
uint64_t minor; uint64_t minor;
}; };
This type is the filesystem identifier that is used as a mandatory This type is the filesystem identifier that is used as a mandatory
attribute. attribute.
2.2.6. fs_location4 2.2.6. fs_location4
struct fs_location4 { struct fs_location4 {
utf8val_must server<>; utf8must server<>;
pathname4 rootpath; pathname4 rootpath;
}; };
2.2.7. fs_locations4 2.2.7. fs_locations4
struct fs_locations4 { struct fs_locations4 {
pathname4 fs_root; pathname4 fs_root;
fs_location4 locations<>; fs_location4 locations<>;
}; };
skipping to change at page 22, line 10 skipping to change at page 22, line 10
}; };
The fattr4 structure is used to represent file and directory The fattr4 structure is used to represent file and directory
attributes. attributes.
The bitmap is a counted array of 32 bit integers used to contain bit The bitmap is a counted array of 32 bit integers used to contain bit
values. The position of the integer in the array that contains bit n values. The position of the integer in the array that contains bit n
can be computed from the expression (n / 32) and its bit within that can be computed from the expression (n / 32) and its bit within that
integer is (n mod 32). integer is (n mod 32).
0 1 0 1
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
| count | 31 .. 0 | 63 .. 32 | | count | 31 .. 0 | 63 .. 32 |
+-----------+-----------+-----------+-- +-----------+-----------+-----------+--
2.2.9. change_info4 2.2.9. change_info4
struct change_info4 { struct change_info4 {
bool atomic; bool atomic;
changeid4 before; changeid4 before;
changeid4 after; changeid4 after;
skipping to change at page 40, line 29 skipping to change at page 40, line 29
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.
skipping to change at page 41, line 31 skipping to change at page 41, line 31
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 GETATTR but not set via SETATTR. If a client attempts to
set a get-only attribute or get a set-only attributes, the server set a get-only attribute or get a set-only attributes, 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
skipping to change at page 47, line 7 skipping to change at page 47, line 7
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., are per file
system attributes the same for all file system's objects. system attributes the same for all file system's objects.
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.
skipping to change at page 48, line 37 skipping to change at page 48, line 37
the same as that of the fileid attribute. the same as that of the fileid attribute.
The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD The mounted_on_fileid attribute is RECOMMENDED, so the server SHOULD
provide it if possible, and for a UNIX-based server, this is provide it if possible, and for a UNIX-based server, this is
straightforward. Usually, mounted_on_fileid will be requested during straightforward. Usually, mounted_on_fileid will be requested during
a READDIR operation, in which case it is trivial (at least for UNIX- a READDIR operation, in which case it is trivial (at least for UNIX-
based servers) to return mounted_on_fileid since it is equal to the based servers) to return mounted_on_fileid since it is equal to the
fileid of a directory entry returned by readdir(). If fileid of a directory entry returned by readdir(). If
mounted_on_fileid is requested in a GETATTR operation, the server mounted_on_fileid is requested in a GETATTR operation, the server
should obey an invariant that has it returning a value that is equal should obey an invariant that has it returning a value that is equal
to the file object's entry in the object's parent directory, i.e. to the file object's entry in the object's parent directory, i.e.,
what readdir() would have returned. Some operating environments what readdir() would have returned. Some operating environments
allow a series of two or more file systems to be mounted onto a allow a series of two or more file systems to be mounted onto a
single mount point. In this case, for the server to obey the single mount point. In this case, for the server to obey the
aforementioned invariant, it will need to find the base mount point, aforementioned invariant, it will need to find the base mount point,
and not the intermediate mount points. and not the intermediate mount points.
5.8.2.20. Attribute 34: no_trunc 5.8.2.20. Attribute 34: no_trunc
If this attribute is TRUE, then if the client uses a file name longer If this attribute is TRUE, then if the client uses a file name longer
than name_max, an error will be returned instead of the name being than name_max, an error will be returned instead of the name being
skipping to change at page 70, line 10 skipping to change at page 70, line 10
be the sole determiner of access. For example: be the sole determiner of access. For example:
o In the case of a file system exported as read-only, the server may o In the case of a file system exported as read-only, the server may
deny write permissions even though an object's ACL grants it. deny write permissions even though an object's ACL grants it.
o Server implementations MAY grant ACE4_WRITE_ACL and ACE4_READ_ACL o Server implementations MAY grant ACE4_WRITE_ACL and ACE4_READ_ACL
permissions to prevent a situation from arising in which there is permissions to prevent a situation from arising in which there is
no valid way to ever modify the ACL. no valid way to ever modify the ACL.
o All servers will allow a user the ability to read the data of the o All servers will allow a user the ability to read the data of the
file when only the execute permission is granted (i.e. If the ACL file when only the execute permission is granted (i.e., If the ACL
denies the user the ACE4_READ_DATA access and allows the user denies the user the ACE4_READ_DATA access and allows the user
ACE4_EXECUTE, the server will allow the user to read the data of ACE4_EXECUTE, the server will allow the user to read the data of
the file). the file).
o Many servers have the notion of owner-override in which the owner o Many servers have the notion of owner-override in which the owner
of the object is allowed to override accesses that are denied by of the object is allowed to override accesses that are denied by
the ACL. This may be helpful, for example, to allow users the ACL. This may be helpful, for example, to allow users
continued access to open files on which the permissions have continued access to open files on which the permissions have
changed. changed.
skipping to change at page 74, line 31 skipping to change at page 74, line 31
and the mode modified as in Section 6.4.1.2 and the mode modified as in Section 6.4.1.2
3. If both mode and ACL are given in the call: 3. If both mode and ACL are given in the call:
In this case, inheritance SHOULD NOT take place, and both In this case, inheritance SHOULD NOT take place, and both
attributes will be set as described in Section 6.4.1.3. attributes will be set as described in Section 6.4.1.3.
4. If neither mode nor ACL are given in the call: 4. If neither mode nor ACL are given in the call:
In the case where an object is being created without any initial In the case where an object is being created without any initial
attributes at all, e.g. an OPEN operation with an opentype4 of attributes at all, e.g., an OPEN operation with an opentype4 of
OPEN4_CREATE and a createmode4 of EXCLUSIVE4, inheritance SHOULD OPEN4_CREATE and a createmode4 of EXCLUSIVE4, inheritance SHOULD
NOT take place. Instead, the server SHOULD set permissions to NOT take place. Instead, the server SHOULD set permissions to
deny all access to the newly created object. It is expected that deny all access to the newly created object. It is expected that
the appropriate client will set the desired attributes in a the appropriate client will set the desired attributes in a
subsequent SETATTR operation, and the server SHOULD allow that subsequent SETATTR operation, and the server SHOULD allow that
operation to succeed, regardless of what permissions the object operation to succeed, regardless of what permissions the object
is created with. For example, an empty ACL denies all is created with. For example, an empty ACL denies all
permissions, but the server should allow the owner's SETATTR to permissions, but the server should allow the owner's SETATTR to
succeed even though WRITE_ACL is implicitly denied. succeed even though WRITE_ACL is implicitly denied.
skipping to change at page 75, line 33 skipping to change at page 75, line 33
set), into two ACEs, one with no inheritance flags, and one with set), into two ACEs, one with no inheritance flags, and one with
ACE4_INHERIT_ONLY_ACE set. This makes it simpler to modify the ACE4_INHERIT_ONLY_ACE set. This makes it simpler to modify the
effective permissions on the directory without modifying the ACE effective permissions on the directory without modifying the ACE
which is to be inherited to the new directory's children. which is to be inherited to the new directory's children.
7. Multi-Server Namespace 7. Multi-Server Namespace
NFSv4 supports attributes that allow a namespace to extend beyond the NFSv4 supports attributes that allow a namespace to extend beyond the
boundaries of a single server. It is RECOMMENDED that clients and boundaries of a single server. It is RECOMMENDED that clients and
servers support construction of such multi-server namespaces. Use of servers support construction of such multi-server namespaces. Use of
such multi-server namespaces is OPTIONAL however, and for many such multi-server namespaces is OPTIONAL, however, and for many
purposes, single-server namespace are perfectly acceptable. Use of purposes, single-server namespaces are perfectly acceptable. Use of
multi-server namespaces can provide many advantages, however, by multi-server namespaces can provide many advantages, however, by
separating a file system's logical position in a namespace from the separating a file system's logical position in a namespace from the
(possibly changing) logistical and administrative considerations that (possibly changing) logistical and administrative considerations that
result in particular file systems being located on particular result in particular file systems being located on particular
servers. servers.
7.1. Location Attributes 7.1. Location Attributes
NFSv4 contains RECOMMENDED attributes that allow file systems on one NFSv4 contains RECOMMENDED attributes that allow file systems on one
server to be associated with one or more instances of that file server to be associated with one or more instances of that file
skipping to change at page 76, line 13 skipping to change at page 76, line 13
The fs_locations RECOMMENDED attribute allows specification of the The fs_locations RECOMMENDED attribute allows specification of the
file system locations where the data corresponding to a given file file system locations where the data corresponding to a given file
system may be found. system may be found.
7.2. File System Presence or Absence 7.2. File System Presence or Absence
A given location in an NFSv4 namespace (typically but not necessarily A given location in an NFSv4 namespace (typically but not necessarily
a multi-server namespace) can have a number of file system instance a multi-server namespace) can have a number of file system instance
locations associated with it via the fs_locations attribute. There locations associated with it via the fs_locations attribute. There
may also be an actual current file system at that location, may also be an actual current file system at that location,
accessible via normal namespace operations (e.g. LOOKUP). In this accessible via normal namespace operations (e.g., LOOKUP). In this
case, the file system is said to be "present" at that position in the case, the file system is said to be "present" at that position in the
namespace and clients will typically use it, reserving use of namespace, and clients will typically use it, reserving use of
additional locations specified via the location-related attributes to additional locations specified via the location-related attributes to
situations in which the principal location is no longer available. situations in which the principal location is no longer available.
When there is no actual file system at the namespace location in When there is no actual file system at the namespace location in
question, the file system is said to be "absent". An absent file question, the file system is said to be "absent". An absent file
system contains no files or directories other than the root. Any system contains no files or directories other than the root. Any
reference to it, except to access a small set of attributes useful in reference to it, except to access a small set of attributes useful in
determining alternate locations, will result in an error, determining alternate locations, will result in an error,
NFS4ERR_MOVED. Note that if the server ever returns the error NFS4ERR_MOVED. Note that if the server ever returns the error
NFS4ERR_MOVED, it MUST support the fs_locations attribute. NFS4ERR_MOVED, it MUST support the fs_locations attribute.
While the error name suggests that we have a case of a file system While the error name suggests that we have a case of a file system
which once was present, and has only become absent later, this is that once was present, and has only become absent later, this is only
only one possibility. A position in the namespace may be permanently one possibility. A position in the namespace may be permanently
absent with the set of file system(s) designated by the location absent with the set of file system(s) designated by the location
attributes being the only realization. The name NFS4ERR_MOVED attributes being the only realization. The name NFS4ERR_MOVED
reflects an earlier, more limited conception of its function, but reflects an earlier, more limited conception of its function, but
this error will be returned whenever the referenced file system is this error will be returned whenever the referenced file system is
absent, whether it has moved or not. absent, whether it has moved or not.
Except in the case of GETATTR-type operations (to be discussed Except in the case of GETATTR-type operations (to be discussed
later), when the current filehandle at the start of an operation is later), when the current filehandle at the start of an operation is
within an absent file system, that operation is not performed and the within an absent file system, that operation is not performed and the
error NFS4ERR_MOVED returned, to indicate that the file system is error NFS4ERR_MOVED is returned, to indicate that the file system is
absent on the current server. absent on the current server.
Because a GETFH cannot succeed if the current filehandle is within an Because a GETFH cannot succeed if the current filehandle is within an
absent file system, filehandles within an absent file system cannot absent file system, filehandles within an absent file system cannot
be transferred to the client. When a client does have filehandles be transferred to the client. When a client does have filehandles
within an absent file system, it is the result of obtaining them when within an absent file system, it is the result of obtaining them when
the file system was present, and having the file system become absent the file system was present, and having the file system become absent
subsequently. subsequently.
It should be noted that because the check for the current filehandle It should be noted that because the check for the current filehandle
skipping to change at page 77, line 30 skipping to change at page 77, line 30
attributes may be obtained for a filehandle within an absent file attributes may be obtained for a filehandle within an absent file
system. This exception only applies if the attribute mask contains system. This exception only applies if the attribute mask contains
at least the fs_locations attribute bit, which indicates the client at least the fs_locations attribute bit, which indicates the client
is interested in a result regarding an absent file system. If it is is interested in a result regarding an absent file system. If it is
not requested, GETATTR will result in an NFS4ERR_MOVED error. not requested, GETATTR will result in an NFS4ERR_MOVED error.
When a GETATTR is done on an absent file system, the set of supported When a GETATTR is done on an absent file system, the set of supported
attributes is very limited. Many attributes, including those that attributes is very limited. Many attributes, including those that
are normally REQUIRED, will not be available on an absent file are normally REQUIRED, will not be available on an absent file
system. In addition to the fs_locations attribute, the following system. In addition to the fs_locations attribute, the following
attributes SHOULD be available on absent file systems, in the case of attributes SHOULD be available on absent file systems. In the case
RECOMMENDED attributes at least to the same degree that they are of RECOMMENDED attributes, they should be available at least to the
available on present file systems. same degree that they are available on present file systems.
fsid: This attribute should be provided so that the client can fsid: This attribute should be provided so that the client can
determine file system boundaries, including, in particular, the determine file system boundaries, including, in particular, the
boundary between present and absent file systems. This value must boundary between present and absent file systems. This value must
be different from any other fsid on the current server and need be different from any other fsid on the current server and need
have no particular relationship to fsids on any particular have no particular relationship to fsids on any particular
destination to which the client might be directed. destination to which the client might be directed.
mounted_on_fileid: For objects at the top of an absent file system mounted_on_fileid: For objects at the top of an absent file system,
this attribute needs to be available. Since the fileid is one this attribute needs to be available. Since the fileid is within
which is within the present parent file system, there should be no the present parent file system, there should be no need to
need to reference the absent file system to provide this reference the absent file system to provide this information.
information.
Other attributes SHOULD NOT be made available for absent file Other attributes SHOULD NOT be made available for absent file
systems, even when it is possible to provide them. The server should systems, even when it is possible to provide them. The server should
not assume that more information is always better and should avoid not assume that more information is always better and should avoid
gratuitously providing additional information. gratuitously providing additional information.
When a GETATTR operation includes a bit mask for the attribute When a GETATTR operation includes a bit mask for the attribute
fs_locations, but where the bit mask includes attributes which are fs_locations, but where the bit mask includes attributes that are not
not supported, GETATTR will not return an error, but will return the supported, GETATTR will not return an error, but will return the mask
mask of the actual attributes supported with the results. of the actual attributes supported with the results.
Handling of VERIFY/NVERIFY is similar to GETATTR in that if the Handling of VERIFY/NVERIFY is similar to GETATTR in that if the
attribute mask does not include fs_locations the error NFS4ERR_MOVED attribute mask does not include fs_locations the error NFS4ERR_MOVED
will result. It differs in that any appearance in the attribute mask will result. It differs in that any appearance in the attribute mask
of an attribute not supported for an absent file system (and note of an attribute not supported for an absent file system (and note
that this will include some normally REQUIRED attributes), will also that this will include some normally REQUIRED attributes) will also
cause an NFS4ERR_MOVED result. cause an NFS4ERR_MOVED result.
7.3.2. READDIR and Absent File Systems 7.3.2. READDIR and Absent File Systems
A READDIR performed when the current filehandle is within an absent A READDIR performed when the current filehandle is within an absent
file system will result in an NFS4ERR_MOVED error, since, unlike the file system will result in an NFS4ERR_MOVED error, since, unlike the
case of GETATTR, no such exception is made for READDIR. case of GETATTR, no such exception is made for READDIR.
Attributes for an absent file system may be fetched via a READDIR for Attributes for an absent file system may be fetched via a READDIR for
a directory in a present file system, when that directory contains a directory in a present file system, when that directory contains
the root directories of one or more absent file systems. In this the root directories of one or more absent file systems. In this
case, the handling is as follows: case, the handling is as follows:
o If the attribute set requested includes fs_locations, then o If the attribute set requested includes fs_locations, then
fetching of attributes proceeds normally and no NFS4ERR_MOVED fetching of attributes proceeds normally and no NFS4ERR_MOVED
indication is returned, even when the rdattr_error attribute is indication is returned, even when the rdattr_error attribute is
requested. requested.
o If the attribute set requested does not include fs_locations, then o If the attribute set requested does not include fs_locations, then
if the rdattr_error attribute is requested, each directory entry if the rdattr_error attribute is requested, each directory entry
for the root of an absent file system, will report NFS4ERR_MOVED for the root of an absent file system will report NFS4ERR_MOVED as
as the value of the rdattr_error attribute. the value of the rdattr_error attribute.
o If the attribute set requested does not include either of the o If the attribute set requested does not include either of the
attributes fs_locations or rdattr_error then the occurrence of the attributes fs_locations or rdattr_error then the occurrence of the
root of an absent file system within the directory will result in root of an absent file system within the directory will result in
the READDIR failing with an NFS4ERR_MOVED error. the READDIR failing with an NFS4ERR_MOVED error.
o The unavailability of an attribute because of a file system's o The unavailability of an attribute because of a file system's
absence, even one that is ordinarily REQUIRED, does not result in absence, even one that is ordinarily REQUIRED, does not result in
any error indication. The set of attributes returned for the root any error indication. The set of attributes returned for the root
directory of the absent file system in that case is simply directory of the absent file system in that case is simply
skipping to change at page 79, line 16 skipping to change at page 79, line 10
The location-bearing attribute of fs_locations provides, together The location-bearing attribute of fs_locations provides, together
with the possibility of absent file systems, a number of important with the possibility of absent file systems, a number of important
facilities in providing reliable, manageable, and scalable data facilities in providing reliable, manageable, and scalable data
access. access.
When a file system is present, these attributes can provide When a file system is present, these attributes can provide
alternative locations, to be used to access the same data, in the alternative locations, to be used to access the same data, in the
event of server failures, communications problems, or other event of server failures, communications problems, or other
difficulties that make continued access to the current file system difficulties that make continued access to the current file system
impossible or otherwise impractical. Under some circumstances impossible or otherwise impractical. Under some circumstances,
multiple alternative locations may be used simultaneously to provide multiple alternative locations may be used simultaneously to provide
higher performance access to the file system in question. Provision higher-performance access to the file system in question. Provision
of such alternate locations is referred to as "replication" although of such alternate locations is referred to as "replication" although
there are cases in which replicated sets of data are not in fact there are cases in which replicated sets of data are not in fact
present, and the replicas are instead different paths to the same present, and the replicas are instead different paths to the same
data. data.
When a file system is present and becomes absent, clients can be When a file system is present and becomes absent, clients can be
given the opportunity to have continued access to their data, at an given the opportunity to have continued access to their data, at an
alternate location. In this case, a continued attempt to use the alternate location. In this case, a continued attempt to use the
data in the now-absent file system will result in an NFS4ERR_MOVED data in the now-absent file system will result in an NFS4ERR_MOVED
error and at that point the successor locations (typically only one error and, at that point, the successor locations (typically only one
but multiple choices are possible) can be fetched and used to although multiple choices are possible) can be fetched and used to
continue access. Transfer of the file system contents to the new continue access. Transfer of the file system contents to the new
location is referred to as "migration", but it should be kept in mind location is referred to as "migration", but it should be kept in mind
that there are cases in which this term can be used, like that there are cases in which this term can be used, like
"replication", when there is no actual data migration per se. "replication", when there is no actual data migration per se.
Where a file system was not previously present, specification of file Where a file system was not previously present, specification of file
system location provides a means by which file systems located on one system location provides a means by which file systems located on one
server can be associated with a namespace defined by another server, server can be associated with a namespace defined by another server,
thus allowing a general multi-server namespace facility. A thus allowing a general multi-server namespace facility. A
designation of such a location, in place of an absent file system, is designation of such a location, in place of an absent file system, is
skipping to change at page 80, line 17 skipping to change at page 80, line 12
impossible or otherwise impractical, the client can use the alternate impossible or otherwise impractical, the client can use the alternate
locations as a way to get continued access to its data. Multiple locations as a way to get continued access to its data. Multiple
locations may be used simultaneously, to provide higher performance locations may be used simultaneously, to provide higher performance
through the exploitation of multiple paths between client and target through the exploitation of multiple paths between client and target
file system. file system.
The alternate locations may be physical replicas of the (typically The alternate locations may be physical replicas of the (typically
read-only) file system data, or they may reflect alternate paths to read-only) file system data, or they may reflect alternate paths to
the same server or provide for the use of various forms of server the same server or provide for the use of various forms of server
clustering in which multiple servers provide alternate ways of clustering in which multiple servers provide alternate ways of
accessing the same physical file system. accessing the same physical file system. How these different modes
of file system transition are represented within the fs_locations
attribute and how the client deals with file system transition issues
will be discussed in detail below.
Multiple server addresses, whether they are derived from a single Multiple server addresses, whether they are derived from a single
entry with a DNS name representing a set of IP addresses, or from entry with a DNS name representing a set of IP addresses or from
multiple entries each with its own server address may correspond to multiple entries each with its own server address, may correspond to
the same actual server. the same actual server.
7.4.2. File System Migration 7.4.2. File System Migration
When a file system is present and becomes absent, clients can be When a file system is present and becomes absent, clients can be
given the opportunity to have continued access to their data, at an given the opportunity to have continued access to their data, at an
alternate location, as specified by the fs_locations attribute. alternate location, as specified by the fs_locations attribute.
Typically, a client will be accessing the file system in question, Typically, a client will be accessing the file system in question,
get an NFS4ERR_MOVED error, and then use the fs_locations attribute get an NFS4ERR_MOVED error, and then use the fs_locations attribute
to determine the new location of the data. to determine the new location of the data.
Such migration can be helpful in providing load balancing or general Such migration can be helpful in providing load balancing or general
resource reallocation. The protocol does not specify how the file resource reallocation. The protocol does not specify how the file
system will be moved between servers. It is anticipated that a system will be moved between servers. It is anticipated that a
number of different server-to-server transfer mechanisms might be number of different server-to-server transfer mechanisms might be
used with the choice left to the server implementer. The NFSv4 used with the choice left to the server implementor. The NFSv4
protocol specifies the method used to communicate the migration event protocol specifies the method used to communicate the migration event
between client and server. between client and server.
The new location may be an alternate communication path to the same The new location may be an alternate communication path to the same
server, or, in the case of various forms of server clustering, server or, in the case of various forms of server clustering, another
another server providing access to the same physical file system. server providing access to the same physical file system. The
client's responsibilities in dealing with this transition depend on
the specific nature of the new access path as well as how and whether
data was in fact migrated. These issues will be discussed in detail
below.
When an alternate location is designated as the target for migration, When an alternate location is designated as the target for migration,
it must designate the same data. Where file systems are writable, a it must designate the same data. Where file systems are writable, a
change made on the original file system must be visible on all change made on the original file system must be visible on all
migration targets. Where a file system is not writable but migration targets. Where a file system is not writable but
represents a read-only copy (possibly periodically updated) of a represents a read-only copy (possibly periodically updated) of a
writable file system, similar requirements apply to the propagation writable file system, similar requirements apply to the propagation
of updates. Any change visible in the original file system must of updates. Any change visible in the original file system must
already be effected on all migration targets, to avoid any already be effected on all migration targets, to avoid any
possibility, that a client in effecting a transition to the migration possibility that a client, in effecting a transition to the migration
target will see any reversion in file system state. target, will see any reversion in file system state.
7.4.3. Referrals 7.4.3. Referrals
Referrals provide a way of placing a file system in a location within Referrals provide a way of placing a file system in a location within
the namespace essentially without respect to its physical location on the namespace essentially without respect to its physical location on
a given server. This allows a single server or a set of servers to a given server. This allows a single server or a set of servers to
present a multi-server namespace that encompasses file systems present a multi-server namespace that encompasses file systems
located on multiple servers. Some likely uses of this include located on multiple servers. Some likely uses of this include
establishment of site-wide or organization-wide namespaces, or even establishment of site-wide or organization-wide namespaces, or even
knitting such together into a truly global namespace. knitting such together into a truly global namespace.
skipping to change at page 81, line 30 skipping to change at page 81, line 33
typically by receiving the error NFS4ERR_MOVED, the actual location typically by receiving the error NFS4ERR_MOVED, the actual location
or locations of the file system can be determined by fetching the or locations of the file system can be determined by fetching the
fs_locations attribute. fs_locations attribute.
The locations-related attribute may designate a single file system The locations-related attribute may designate a single file system
location or multiple file system locations, to be selected based on location or multiple file system locations, to be selected based on
the needs of the client. the needs of the client.
Use of multi-server namespaces is enabled by NFSv4 but is not Use of multi-server namespaces is enabled by NFSv4 but is not
required. The use of multi-server namespaces and their scope will required. The use of multi-server namespaces and their scope will
depend on the applications used, and system administration depend on the applications used and system administration
preferences. preferences.
Multi-server namespaces can be established by a single server Multi-server namespaces can be established by a single server
providing a large set of referrals to all of the included file providing a large set of referrals to all of the included file
systems. Alternatively, a single multi-server namespace may be systems. Alternatively, a single multi-server namespace may be
administratively segmented with separate referral file systems (on administratively segmented with separate referral file systems (on
separate servers) for each separately-administered portion of the separate servers) for each separately administered portion of the
namespace. Any segment or the top-level referral file system may use namespace. The top-level referral file system or any segment may use
replicated referral file systems for higher availability. replicated referral file systems for higher availability.
Generally, multi-server namespaces are for the most part uniform, in Generally, multi-server namespaces are for the most part uniform, in
that the same data made available to one client at a given location that the same data made available to one client at a given location
in the namespace is made available to all clients at that location. in the namespace is made available to all clients at that location.
7.5. Location Entries and Server Identity 7.5. Location Entries and Server Identity
As mentioned above, a single location entry may have a server address As mentioned above, a single location entry may have a server address
target in the form of a DNS name which may represent multiple IP target in the form of a DNS name that may represent multiple IP
addresses, while multiple location entries may have their own server addresses, while multiple location entries may have their own server
address targets, that reference the same server. address targets that reference the same server.
When multiple addresses for the same server exist, the client may When multiple addresses for the same server exist, the client may
assume that for each file system in the namespace of a given server assume that for each file system in the namespace of a given server
network address, there exist file systems at corresponding namespace network address, there exist file systems at corresponding namespace
locations for each of the other server network addresses. It may do locations for each of the other server network addresses. It may do
this even in the absence of explicit listing in fs_locations. Such this even in the absence of explicit listing in fs_locations. Such
corresponding file system locations can be used as alternate corresponding file system locations can be used as alternate
locations, just as those explicitly specified via the fs_locations locations, just as those explicitly specified via the fs_locations
attribute. attribute.
If a single location entry designates multiple server IP addresses, If a single location entry designates multiple server IP addresses,
the client cannot assume that these addresses are multiple paths to the client cannot assume that these addresses are multiple paths to
the same server. In most case they will be, but the client MUST the same server. In most cases, they will be, but the client MUST
verify that before acting on that assumption. When two server verify that before acting on that assumption. When two server
addresses are designated by a single location entry and they addresses are designated by a single location entry and they
correspond to different servers, this normally indicates some sort of correspond to different servers, this normally indicates some sort of
misconfiguration, and so the client should avoid use such location misconfiguration, and so the client should avoid using such location
entries when alternatives are available. When they are not, clients entries when alternatives are available. When they are not, clients
should pick one of IP addresses and use it, without using others that should pick one of IP addresses and use it, without using others that
are not directed to the same server. are not directed to the same server.
7.6. Additional Client-side Considerations 7.6. Additional Client-Side Considerations
When clients make use of servers that implement referrals, When clients make use of servers that implement referrals,
replication, and migration, care should be taken so that a user who replication, and migration, care should be taken that a user who
mounts a given file system that includes a referral or a relocated mounts a given file system that includes a referral or a relocated
file system continues to see a coherent picture of that user-side file system continues to see a coherent picture of that user-side
file system despite the fact that it contains a number of server-side file system despite the fact that it contains a number of server-side
file systems which may be on different servers. file systems that may be on different servers.
One important issue is upward navigation from the root of a server- One important issue is upward navigation from the root of a server-
side file system to its parent (specified as ".." in UNIX), in the side file system to its parent (specified as ".." in UNIX), in the
case in which it transitions to that file system as a result of case in which it transitions to that file system as a result of
referral, migration, or a transition as a result of replication. referral, migration, or a transition as a result of replication.
When the client is at such a point, and it needs to ascend to the When the client is at such a point, and it needs to ascend to the
parent, it must go back to the parent as seen within the multi-server parent, it must go back to the parent as seen within the multi-server
namespace rather issuing a LOOKUPP call to the server, which would namespace rather than sending a LOOKUPP operation to the server,
result in the parent within that server's single-server namespace. which would result in the parent within that server's single-server
In order to do this, the client needs to remember the filehandles namespace. In order to do this, the client needs to remember the
that represent such file system roots, and use these instead of filehandles that represent such file system roots and use these
issuing a LOOKUPP to the current server. This will allow the client instead of issuing a LOOKUPP operation to the current server. This
to present to applications a consistent namespace, where upward will allow the client to present to applications a consistent
navigation and downward navigation are consistent. namespace, where upward navigation and downward navigation are
consistent.
Another issue concerns refresh of referral locations. When referrals Another issue concerns refresh of referral locations. When referrals
are used extensively, they may change as server configurations are used extensively, they may change as server configurations
change. It is expected that clients will cache information related change. It is expected that clients will cache information related
to traversing referrals so that future client side requests are to traversing referrals so that future client-side requests are
resolved locally without server communication. This is usually resolved locally without server communication. This is usually
rooted in client-side name lookup caching. Clients should rooted in client-side name look up caching. Clients should
periodically purge this data for referral points in order to detect periodically purge this data for referral points in order to detect
changes in location information. When the change_policy attribute changes in location information.
changes for directories that hold referral entries or for the
referral entries themselves, clients should consider any associated
cached referral information to be out of date.
7.7. Effecting File System Transitions 7.7. Effecting File System Transitions
Transitions between file system instances, whether due to switching Transitions between file system instances, whether due to switching
between replicas upon server unavailability, or in response to between replicas upon server unavailability or to server-initiated
server-initiated migration events are best dealt with together. This migration events, are best dealt with together. This is so even
is so even though for the server, pragmatic considerations will though, for the server, pragmatic considerations will normally force
normally force different implementation strategies for planned and different implementation strategies for planned and unplanned
unplanned transitions. Even though the prototypical use cases of transitions. Even though the prototypical use cases of replication
replication and migration contain distinctive sets of features, when and migration contain distinctive sets of features, when all
all possibilities for these operations are considered, there is an possibilities for these operations are considered, there is an
underlying unity of these operations, from the client's point of underlying unity of these operations, from the client's point of
view, that makes treating them together desirable. view, that makes treating them together desirable.
A number of methods are possible for servers to replicate data and to A number of methods are possible for servers to replicate data and to
track client state in order to allow clients to transition between track client state in order to allow clients to transition between
file system instances with a minimum of disruption. Such methods file system instances with a minimum of disruption. Such methods
vary between those that use inter-server clustering techniques to vary between those that use inter-server clustering techniques to
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. The NFSv4.0 with regard to that spectrum of transition methods. In fact, there
protocol does not provide the servers a means of communicating the are many valid choices, depending on client and application
transiation methods. In the NFSv4.1 protocol [27], an additional requirements and their interaction with server implementation
attribute "fs_locations_info" is presented, which will define the choices. The NFSv4.0 protocol does not provide the servers a means
specific choices that can be made, how these choices are communicated of communicating the transition methods. In the NFSv4.1 protocol
to the client and how the client is to deal with any discontinuities. [27], an additional attribute "fs_locations_info" is presented, which
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
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 issues as a way of illustrating the transition scenarios that server implementation choices as a way of illustrating the transition
clients may deal with. The intent here is not to define or limit scenarios that clients may deal with. The intent here is not to
server implementations but rather to illustrate the range of issues define or limit server implementations but rather to illustrate the
that clients may face. Again, as the NFSv4.0 protocol does not have range of issues that clients may face. Again, as the NFSv4.0
an explict means of communicating these issues to the client, the protocol does not have an explict means of communicating these issues
intent is to document the problems that can be faced in a multi- to the client, the intent is to document the problems that can be
server name space and allow the client to use the inferred faced in a multi-server name space and allow the client to use the
transitions available via fs_locations and other attributes (see inferred transitions available via fs_locations and other attributes
Section 7.9.1). (see Section 7.9.1).
In the discussion below, references will be made to a file system In the discussion below, references will be made to a file system
having a particular property or of two file systems (typically the having a particular property or to two file systems (typically the
source and destination) belonging to a common class of any of several source and destination) belonging to a common class of any of several
types. Two file systems that belong to such a class share some types. Two file systems that belong to such a class share some
important aspect of file system behavior that clients may depend upon important aspects of file system behavior that clients may depend
when present, to easily effect a seamless transition between file upon when present, to easily effect a seamless transition between
system instances. Conversely, where the file systems do not belong file system instances. Conversely, where the file systems do not
to such a common class, the client has to deal with various sorts of belong to such a common class, the client has to deal with various
implementation discontinuities which may cause performance or other sorts of implementation discontinuities that may cause performance or
issues in effecting a transition. other issues in effecting a transition.
While fs_locations is available, default assumptions with regard to While fs_locations is available, default assumptions with regard to
such classifications have to be inferred (see Section 7.9.1 for such classifications have to be inferred (see Section 7.9.1 for
details). details).
In cases in which one server is expected to accept opaque values from In cases in which one server is expected to accept opaque values from
the client that originated from another server, the servers SHOULD the client that originated from another server, the servers SHOULD
encode the "opaque" values in big endian byte order. If this is encode the "opaque" values in big-endian byte order. If this is
done, servers acting as replicas or immigrating file systems will be done, servers acting as replicas or immigrating file systems will be
able to parse values like stateids, directory cookies, filehandles, able to parse values like stateids, directory cookies, filehandles,
etc. even if their native byte order is different from that of other etc., even if their native byte order is different from that of other
servers cooperating in the replication and migration of the file servers cooperating in the replication and migration of the file
system. system.
7.7.1. File System Transitions and Simultaneous Access 7.7.1. File System Transitions and Simultaneous Access
When a single file system may be accessed at multiple locations, When a single file system may be accessed at multiple locations,
whether this is because of an indication of file system identity as either because of an indication of file system identity as reported
reported by the fs_locations attribute, the client will, depending on by the fs_locations attribute, the client will, depending on specific
specific circumstances as discussed below, either: circumstances as discussed below, either:
o The client accesses multiple instances simultaneously, as o Access multiple instances simultaneously, each of which represents
representing alternate paths to the same data and metadata. an alternate path to the same data and metadata.
o The client accesses one instance (or set of instances) and then o Acesses one instance (or set of instances) and then transition to
transitions to an alternative instance (or set of instances) as a an alternative instance (or set of instances) as a result of
result of network issues, server unresponsiveness, or server- network issues, server unresponsiveness, or server-directed
directed migration. migration.
7.7.2. Filehandles and File System Transitions 7.7.2. Filehandles and File System Transitions
There are a number of ways in which filehandles can be handled across There are a number of ways in which filehandles can be handled across
a file system transition. These can be divided into two broad a file system transition. These can be divided into two broad
classes depending upon whether the two file systems across which the classes depending upon whether the two file systems across which the
transition happens share sufficient state to effect some sort of transition happens share sufficient state to effect some sort of
continuity of file system handling. continuity of file system handling.
When there is no such co-operation in filehandle assignment, the two When there is no such cooperation in filehandle assignment, the two
file systems are reported as being in different _handle_ classes. In file systems are reported as being in different handle classes. In
this case, all filehandles are assumed to expire as part of the file this case, all filehandles are assumed to expire as part of the file
system transition. Note that this behavior does not depend on system transition. Note that this behavior does not depend on
fh_expire_type attribute and depends on the specification of the fh_expire_type attribute and depends on the specification of the
FH4_VOL_MIGRATION bit. FH4_VOL_MIGRATION bit.
When there is co-operation in filehandle assignment, the two file When there is co-operation in filehandle assignment, the two file
systems are reported as being in the same _handle_ classes. In this systems are reported as being in the same handle classes. In this
case, persistent filehandles remain valid after the file system case, persistent filehandles remain valid after the file system
transition, while volatile filehandles (excluding those that are only transition, while volatile filehandles (excluding those that are only
volatile due to the FH4_VOL_MIGRATION bit) are subject to expiration volatile due to the FH4_VOL_MIGRATION bit) are subject to expiration
on the target server. on the target server.
7.7.3. Fileids and File System Transitions 7.7.3. Fileids and File System Transitions
The issue of continuity of fileids in the event of a file system The issue of continuity of fileids in the event of a file system
transition needs to be addressed. The general expectation had been transition needs to be addressed. The general expectation is that in
that in situations in which the two file system instances are created situations in which the two file system instances are created by a
by a single vendor using some sort of file system image copy, fileids single vendor using some sort of file system image copy, fileids will
will be consistent across the transition while in the analogous be consistent across the transition, while in the analogous multi-
multi-vendor transitions they will not. This poses difficulties, vendor transitions they will not. This poses difficulties,
especially for the client without special knowledge of the transition especially for the client without special knowledge of the transition
mechanisms adopted by the server. Note that although fileid is not a mechanisms adopted by the server. Note that although fileid is not a
REQUIRED attribute, many servers support fileids and many clients REQUIRED attribute, many servers support fileids and many clients
provide API's that depend on fileids. provide APIs that depend on fileids.
It is important to note that while clients themselves may have no It is important to note that while clients themselves may have no
trouble with a fileid changing as a result of a file system trouble with a fileid changing as a result of a file system
transition event, applications do typically have access to the fileid transition event, applications do typically have access to the fileid
(e.g. via stat), and the result of this is that an application may (e.g., via stat). The result is that an application may work
work perfectly well if there is no file system instance transition or perfectly well if there is no file system instance transition or if
if any such transition is among instances created by a single vendor, any such transition is among instances created by a single vendor,
yet be unable to deal with the situation in which a multi-vendor yet be unable to deal with the situation in which a multi-vendor
transition occurs, at the wrong time. transition occurs at the wrong time.
Providing the same fileids in a multi-vendor (multiple server Providing the same fileids in a multi-vendor (multiple server
vendors) environment has generally been held to be quite difficult. vendors) environment has generally been held to be quite difficult.
While there is work to be done, it needs to be pointed out that this While there is work to be done, it needs to be pointed out that this
difficulty is partly self-imposed. Servers have typically identified difficulty is partly self-imposed. Servers have typically identified
fileid with inode number, i.e. with a quantity used to find the file fileid with inode number, i.e., with a quantity used to find the file
in question. This identification poses special difficulties for in question. This identification poses special difficulties for
migration of a file system between vendors where assigning the same migration of a file system between vendors where assigning the same
index to a given file may not be possible. Note here that a fileid index to a given file may not be possible. Note here that a fileid
is not required to be useful to find the file in question, only that is not required to be useful to find the file in question, only that
it is unique within the given file system. Servers prepared to it is unique within the given file system. Servers prepared to
accept a fileid as a single piece of metadata and store it apart from accept a fileid as a single piece of metadata and store it apart from
the value used to index the file information can relatively easily the value used to index the file information can relatively easily
maintain a fileid value across a migration event, allowing a truly maintain a fileid value across a migration event, allowing a truly
transparent migration event. transparent migration event.
In any case, where servers can provide continuity of fileids, they In any case, where servers can provide continuity of fileids, they
should, and the client should be able to find out that such should, and the client should be able to find out that such
continuity is available and take appropriate action. Information continuity is available and take appropriate action. Information
about the continuity (or lack thereof) of fileids across a file about the continuity (or lack thereof) of fileids across a file
system transition is represented by specifying whether the file system transition is represented by specifying whether the file
systems in question are of the same _fileid_ class. systems in question are of the same fileid class.
Note that when consistent fileids do not exist across a transition Note that when consistent fileids do not exist across a transition
(either because there is no continuity of fileids or because fileid (either because there is no continuity of fileids or because fileid
is not a supported attribute on one of instances involved), and there is not a supported attribute on one of instances involved), and there
are no reliable filehandles across a transition event (either because are no reliable filehandles across a transition event (either because
there is no filehandle continuity or because the filehandles are there is no filehandle continuity or because the filehandles are
volatile), the client is in a position where it cannot verify that volatile), the client is in a position where it cannot verify that
files it was accessing before the transition are the same objects. files it was accessing before the transition are the same objects.
It is forced to assume that no object has been renamed, and, unless It is forced to assume that no object has been renamed, and, unless
there are guarantees that provide this (e.g. the file system is read- there are guarantees that provide this (e.g., the file system is
only), problems for applications may occur. Therefore, use of such read-only), problems for applications may occur. Therefore, use of
configurations should be limited to situations where the problems such configurations should be limited to situations where the
that this may cause can be tolerated. problems that this may cause can be tolerated.
7.7.4. Fsids and File System Transitions 7.7.4. Fsids and File System Transitions
Since fsids are generally only unique within a per-server basis, it Since fsids are generally only unique within a per-server basis, it
is likely that they will change during a file system transition. is likely that they will change during a file system transition.
Clients should not make the fsids received from the server visible to Clients should not make the fsids received from the server visible to
applications since they may not be globally unique, and because they applications since they may not be globally unique, and because they
may change during a file system transition event. Applications are may change during a file system transition event. Applications are
best served if they are isolated from such transitions to the extent best served if they are isolated from such transitions to the extent
possible. possible.
7.7.5. The Change Attribute and File System Transitions 7.7.5. The Change Attribute and File System Transitions
Since the change attribute is defined as a server-specific one, Since the change attribute is defined as a server-specific one,
change attributes fetched from one server are normally presumed to be change attributes fetched from one server are normally presumed to be
invalid on another server. Such a presumption is troublesome since invalid on another server. Such a presumption is troublesome since
it would invalidate all cached change attributes, requiring it would invalidate all cached change attributes, requiring
refetching. Even more disruptive, the absence of any assured refetching. Even more disruptive, the absence of any assured
continuity for the change attribute means that even if the same value continuity for the change attribute means that even if the same value
is retrieved on refetch no conclusions can drawn as to whether the is retrieved on refetch, no conclusions can be drawn as to whether
object in question has changed. The identical change attribute could the object in question has changed. The identical change attribute
be merely an artifact of a modified file with a different change could be merely an artifact of a modified file with a different
attribute construction algorithm, with that new algorithm just change attribute construction algorithm, with that new algorithm just
happening to result in an identical change value. happening to result in an identical change value.
When the two file systems have consistent change attribute formats, When the two file systems have consistent change attribute formats,
and we say that they are in the same _change_ class, the client may and we say that they are in the same change class, the client may
assume a continuity of change attribute construction and handle this assume a continuity of change attribute construction and handle this
situation just as it would be handled without any file system situation just as it would be handled without any file system
transition. transition.
7.7.6. Lock State and File System Transitions 7.7.6. Lock State and File System Transitions
In a file system transition, the client needs to handle cases in In a file system transition, the client needs to handle cases in
which the two servers have cooperated in state management and in which the two servers have cooperated in state management and in
which they have not. Cooperation by two servers in state management which they have not. Cooperation by two servers in state management
requires coordination of client IDs. Before the client attempts to requires coordination of client IDs. Before the client attempts to
skipping to change at page 87, line 31 skipping to change at page 87, line 36
This state transfer will reduce disruption to the client when a file This state transfer will reduce disruption to the client when a file
system transition occurs. If the servers are successful in system transition occurs. If the servers are successful in
transferring all state, the client can attempt to establish sessions transferring all state, the client can attempt to establish sessions
associated with the client ID used for the source file system associated with the client ID used for the source file system
instance. If the server accepts that as a valid client ID, then the instance. If the server accepts that as a valid client ID, then the
client may use the existing stateids associated with that client ID client may use the existing stateids associated with that client ID
for the old file system instance in connection with that same client for the old file system instance in connection with that same client
ID in connection with the transitioned file system instance. ID in connection with the transitioned file system instance.
File systems co-operating in state management may actually share File systems cooperating in state management may actually share state
state or simply divide the identifier space so as to recognize (and or simply divide the identifier space so as to recognize (and reject
reject as stale) each other's stateids and client IDs. Servers which as stale) each other's stateids and client IDs. Servers that do
do share state may not do so under all conditions or at all times. share state may not do so under all conditions or at all times. If
The requirement for the server is that if it cannot be sure in the server cannot be sure when accepting a client ID that it reflects
accepting a client ID that it reflects the locks the client was the locks the client was given, the server must treat all associated
given, it must treat all associated state as stale and report it as state as stale and report it as such to the client.
such to the client.
The client must establish a new client ID on the destination, if it The client must establish a new client ID on the destination, if it
does not have one already, and reclaim locks if possible. In this does not have one already, and reclaim locks if allowed by the
case, old stateids and client IDs should not be presented to the new server. In this case, old stateids and client IDs should not be
server since there is no assurance that they will not conflict with presented to the new server since there is no assurance that they
IDs valid on that server. will not conflict with IDs valid on that server.
When actual locks are not known to be maintained, the destination When actual locks are not known to be maintained, the destination
server may establish a grace period specific to the given file server may establish a grace period specific to the given file
system, with non-reclaim locks being rejected for that file system, system, with non-reclaim locks being rejected for that file system,
even though normal locks are being granted for other file systems. even though normal locks are being granted for other file systems.
Clients should not infer the absence of a grace period for file Clients should not infer the absence of a grace period for file
systems being transitioned to a server from responses to requests for systems being transitioned to a server from responses to requests for
other file systems. other file systems.
In the case of lock reclamation for a given file system after a file In the case of lock reclamation for a given file system after a file
system transition, edge conditions can arise similar to those for system transition, edge conditions can arise similar to those for
reclaim after server restart (although in the case of the planned reclaim after server restart (although in the case of the planned
state transfer associated with migration, these can be avoided by state transfer associated with migration, these can be avoided by
securely recording lock state as part of state migration). Unless securely recording lock state as part of state migration). Unless
the destination server can guarantee that locks will not be the destination server can guarantee that locks will not be
incorrectly granted, the destination server should not allow lock incorrectly granted, the destination server should not allow lock
reclaims and avoid establishing a grace period. (See Section 9.14 reclaims and should avoid establishing a grace period. (See
for further details.) Section 9.14 for further details.)
Information about client identity may be propagated between servers Information about client identity may be propagated between servers
in the form of client_owner4 and associated verifiers, under the in the form of client_owner4 and associated verifiers, under the
assumption that the client presents the same values to all the assumption that the client presents the same values to all the
servers with which it deals. servers with which it deals.
Servers are encouraged to provide facilities to allow locks to be Servers are encouraged to provide facilities to allow locks to be
reclaimed on the new server after a file system transition. Often reclaimed on the new server after a file system transition. Often
such facilities may not be available and client should be prepared to such facilities may not be available and client should be prepared to
re-obtain locks, even though it is possible that the client may have re-obtain locks, even though it is possible that the client may have
its LOCK or OPEN request denied due to a conflicting lock. its LOCK or OPEN request denied due to a conflicting lock.
The consequences of having no facilities available to reclaim locks The consequences of having no facilities available to reclaim locks
on the sew server will depend on the type of environment. In some on the new server will depend on the type of environment. In some
environments, such as the transition between read-only file systems, environments, such as the transition between read-only file systems,
such denial of locks should not pose large difficulties in practice. such denial of locks should not pose large difficulties in practice.
When an attempt to re-establish a lock on a new server is denied, the When an attempt to re-establish a lock on a new server is denied, the
client should treat the situation as if its original lock had been client should treat the situation as if its original lock had been
revoked. Note that when the lock is granted, the client cannot revoked. Note that when the lock is granted, the client cannot
assume that no conflicting lock could have been granted in the assume that no conflicting lock could have been granted in the
interim. Where change attribute continuity is present, the client interim. Where change attribute continuity is present, the client
may check the change attribute to check for unwanted file may check the change attribute to check for unwanted file
modifications. Where even this is not available, and the file system modifications. Where even this is not available, and the file system
is not read-only, a client may reasonably treat all pending locks as is not read-only, a client may reasonably treat all pending locks as
having been revoked. having been revoked.
7.7.6.1. Transitions and the Lease_time Attribute 7.7.6.1. Transitions and the Lease_time Attribute
In order that the client may appropriately manage its leases in the In order that the client may appropriately manage its lease in the
case of a file system transition, the destination server must case of a file system transition, the destination server must
establish proper values for the lease_time attribute. establish proper values for the lease_time attribute.
When state is transferred transparently, that state should include When state is transferred transparently, that state should include
the correct value of the lease_time attribute. The lease_time the correct value of the lease_time attribute. The lease_time
attribute on the destination server must never be less than that on attribute on the destination server must never be less than that on
the source since this would result in premature expiration of leases the source, since this would result in premature expiration of a
granted by the source server. Upon transitions in which state is lease granted by the source server. Upon transitions in which state
transferred transparently, the client is under no obligation to re- is transferred transparently, the client is under no obligation to
fetch the lease_time attribute and may continue to use the value refetch the lease_time attribute and may continue to use the value
previously fetched (on the source server). previously fetched (on the source server).
If state has not been transferred transparently because the client ID If state has not been transferred transparently because the client ID
is rejected when presented to the new server, the client should fetch is rejected when presented to the new server, the client should fetch
the value of lease_time on the new (i.e. destination) server, and use the value of lease_time on the new (i.e., destination) server, and
it for subsequent locking requests. However the server must respect use it for subsequent locking requests. However, the server must
a grace period at least as long as the lease_time on the source respect a grace period of at least as long as the lease_time on the
server, in order to ensure that clients have ample time to reclaim source server, in order to ensure that clients have ample time to
their lock before potentially conflicting non-reclaimed locks are reclaim their lock before potentially conflicting non-reclaimed locks
granted. are granted.
7.7.7. Write Verifiers and File System Transitions 7.7.7. Write Verifiers and File System Transitions
In a file system transition, the two file systems may be clustered in In a file system transition, the two file systems may be clustered in
the handling of unstably written data. When this is the case, and the handling of unstably written data. When this is the case, and
the two file systems belong to the same _write-verifier_ class, write the two file systems belong to the same write-verifier class, write
verifiers returned from one system may be compared to those returned verifiers returned from one system may be compared to those returned
by the other and superfluous writes avoided. by the other and superfluous writes avoided.
When two file systems belong to different _write-verifier_ classes, When two file systems belong to different write-verifier classes, any
any verifier generated by one must not be compared to one provided by verifier generated by one must not be compared to one provided by the
the other. Instead, it should be treated as not equal even when the other. Instead, it should be treated as not equal even when the
values are identical. values are identical.
7.7.8. Readdir Cookies and Verifiers and File System Transitions 7.7.8. Readdir Cookies and Verifiers and File System Transitions
In a file system transition, the two file systems may be consistent In a file system transition, the two file systems may be consistent
in their handling of READDIR cookies and verifiers. When this is the in their handling of READDIR cookies and verifiers. When this is the
case, and the two file systems belong to the same _readdir_ class, case, and the two file systems belong to the same readdir class,
READDIR cookies and verifiers from one system may be recognized by READDIR cookies and verifiers from one system may be recognized by
the other and READDIR operations started on one server may be validly the other and READDIR operations started on one server may be validly
continued on the other, simply by presenting the cookie and verifier continued on the other, simply by presenting the cookie and verifier
returned by a READDIR operation done on the first file system to the returned by a READDIR operation done on the first file system to the
second. second.
When two file systems belong to different _readdir_ classes, any When two file systems belong to different readdir classes, any
READDIR cookie and verifier generated by one is not valid on the READDIR cookie and verifier generated by one is not valid on the
second, and must not be presented to that server by the client. The second, and must not be presented to that server by the client. The
client should act as if the verifier was rejected. client should act as if the verifier was rejected.
7.7.9. File System Data and File System Transitions 7.7.9. File System Data and File System Transitions
When multiple replicas exist and are used simultaneously or in When multiple replicas exist and are used simultaneously or in
succession by a client, applications using them will normally expect succession by a client, applications using them will normally expect
that they contain data the same data or data which is consistent with that they contain either the same data or data that is consistent
the normal sorts of changes that are made by other clients updating with the normal sorts of changes that are made by other clients
the data of the file system. (with metadata being the same to the updating the data of the file system (with metadata being the same to
degree inferred by the fs_locations attribute). However, when the degree inferred by the fs_locations attribute). However, when
multiple file systems are presented as replicas of one another, the multiple file systems are presented as replicas of one another, the
precise relationship between the data of one and the data of another precise relationship between the data of one and the data of another
is not, as a general matter, specified by the NFSv4 protocol. It is is not, as a general matter, specified by the NFSv4 protocol. It is
quite possible to present as replicas file systems where the data of quite possible to present as replicas file systems where the data of
those file systems is sufficiently different that some applications those file systems is sufficiently different that some applications
have problems dealing with the transition between replicas. The have problems dealing with the transition between replicas. The
namespace will typically be constructed so that applications can namespace will typically be constructed so that applications can
choose an appropriate level of support, so that in one position in choose an appropriate level of support, so that in one position in
the namespace a varied set of replicas will be listed while in the namespace a varied set of replicas will be listed, while in
another only those that are up-to-date may be considered replicas. another only those that are up-to-date may be considered replicas.
The protocol does define three special cases of the relationship The protocol does define four special cases of the relationship among
among replicas to be specified by the server and relied upon by replicas to be specified by the server and relied upon by clients:
clients:
o When multiple server addresses correspond to the same actual o When multiple server addresses correspond to the same actual
server, the client may depend on the fact that changes to data, server, the client may depend on the fact that changes to data,
metadata, or locks made on one file system are immediately metadata, or locks made on one file system are immediately
reflected on others. reflected on others.
o When multiple replicas exist and are used simultaneously by a o When multiple replicas exist and are used simultaneously by a
client, they must designate the same data. Where file systems are client, they must designate the same data. Where file systems are
writable, a change made on one instance must be visible on all writable, a change made on one instance must be visible on all
instances, immediately upon the earlier of the return of the instances, immediately upon the earlier of the return of the
modifying requester or the visibility of that change on any of the modifying requester or the visibility of that change on any of the
associated replicas. This allows a client to use these replicas associated replicas. This allows a client to use these replicas
simultaneously without any special adaptation to the fact that simultaneously without any special adaptation to the fact that
there are multiple replicas. In this case, locks, whether shared there are multiple replicas. In this case, locks (whether share
or byte-range, and delegations obtained one replica are reservations or byte-range locks), and delegations obtained on one
immediately reflected on all replicas, even though these locks replica are immediately reflected on all replicas, even though
will be managed under a set of client IDs. these locks will be managed under a set of client IDs.
o When one replica is designated as the successor instance to o When one replica is designated as the successor instance to
another existing instance after return NFS4ERR_MOVED (i.e. the another existing instance after return NFS4ERR_MOVED (i.e., the
case of migration), the client may depend on the fact that all case of migration), the client may depend on the fact that all
changes securely made to data (uncommitted writes are dealt with changes written to stable storage on the original instance are
in Section 7.7.7) on the original instance are made to the written to stable storage of the successor (uncommitted writes are
successor image. dealt with in Section 7.7.7).
o Where a file system is not writable but represents a read-only o Where a file system is not writable but represents a read-only
copy (possibly periodically updated) of a writable file system, copy (possibly periodically updated) of a writable file system,
clients have similar requirements with regard to the propagation clients have similar requirements with regard to the propagation
of updates. They may need a guarantee that any change visible on of updates. They may need a guarantee that any change visible on
the original file system instance must be immediately visible on the original file system instance must be immediately visible on
any replica before the client transitions access to that replica, any replica before the client transitions access to that replica,
in order to avoid any possibility that a client, in effecting a in order to avoid any possibility that a client, in effecting a
transition to a replica, will see any reversion in file system transition to a replica, will see any reversion in file system
state. Since these file systems are presumed not to be suitable state. Since these file systems are presumed to be unsuitable for
for simultaneous use, there is no specification of how locking is simultaneous use, there is no specification of how locking is
handled and it generally will be the case that locks obtained one handled; in general, locks obtained on one file system will be
file system will be separate from those on others. Since these separate from those on others. Since these are going to be read-
are going to be read-only file systems, this is not expected to only file systems, this is not expected to pose an issue for
pose an issue for clients or applications. clients or applications.
7.8. Effecting File System Referrals 7.8. Effecting File System Referrals
Referrals are effected when an absent file system is encountered, and Referrals are effected when an absent file system is encountered, and
one or more alternate locations are made available by the one or more alternate locations are made available by the
fs_locations attribute. The client will typically get an fs_locations attribute. The client will typically get an
NFS4ERR_MOVED error, fetch the appropriate location information and NFS4ERR_MOVED error, fetch the appropriate location information, and
proceed to access the file system on a different server, even though proceed to access the file system on a different server, even though
it retains its logical position within the original namespace. it retains its logical position within the original namespace.
Referrals differ from migration events in that they happen only when Referrals differ from migration events in that they happen only when
the client has not previously referenced the file system in question the client has not previously referenced the file system in question
(so there is nothing to transition). Referrals can only come into (so there is nothing to transition). Referrals can only come into
effect when an absent file system is encountered at its root. effect when an absent file system is encountered at its root.
The examples given in the sections below are somewhat artificial in The examples given in the sections below are somewhat artificial in
that an actual client will not typically do a multi-component lookup, that an actual client will not typically do a multi-component look
but will have cached information regarding the upper levels of the up, but will have cached information regarding the upper levels of
name hierarchy. However, these example are chosen to make the the name hierarchy. However, these example are chosen to make the
required behavior clear and easy to put within the scope of a small required behavior clear and easy to put within the scope of a small
number of requests, without getting unduly into details of how number of requests, without getting unduly into details of how
specific clients might choose to cache things. specific clients might choose to cache things.
7.8.1. Referral Example (LOOKUP) 7.8.1. Referral Example (LOOKUP)
Let us suppose that the following COMPOUND is sent in an environment Let us suppose that the following COMPOUND is sent in an environment
in which /this/is/the/path is absent from the target server. This in which /this/is/the/path is absent from the target server. This
may be for a number of reasons. It may be the case that the file may be for a number of reasons. It may be the case that the file
system has moved, or, it may be the case that the target server is system has moved, or it may be the case that the target server is
functioning mainly, or solely, to refer clients to the servers on functioning mainly, or solely, to refer clients to the servers on
which various file systems are located. which various file systems are located.
o PUTROOTFH o PUTROOTFH
o LOOKUP "this" o LOOKUP "this"
o LOOKUP "is" o LOOKUP "is"
o LOOKUP "the" o LOOKUP "the"
o LOOKUP "path" o LOOKUP "path"
o GETFH o GETFH
o GETATTR fsid,fileid,size,time_modify o GETATTR(fsid,fileid,size,time_modify)
Under the given circumstances, the following will be the result. Under the given circumstances, the following will be the result.
o PUTROOTFH --> NFS_OK. The current fh is now the root of the o PUTROOTFH --> NFS_OK. The current fh is now the root of the
pseudo-fs. pseudo-fs.
o LOOKUP "this" --> NFS_OK. The current fh is for /this and is o LOOKUP "this" --> NFS_OK. The current fh is for /this and is
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and
is within the pseudo-fs. is within the pseudo-fs.
o LOOKUP "path" --> NFS_OK. The current fh is for /this/is/the/path o LOOKUP "path" --> NFS_OK. The current fh is for /this/is/the/path
and is within a new, absent file system, but ... the client will and is within a new, absent file system, but ... the client will
never see the value of that fh. never see the value of that fh.
o GETFH --> NFS4ERR_MOVED. Fails because current fh is in an absent o GETFH --> NFS4ERR_MOVED. Fails because current fh is in an absent
file system at the start of the operation and the spec makes no file system at the start of the operation, and the specification
exception for GETFH. makes no exception for GETFH.
o GETATTR fsid,fileid,size,time_modify. Not executed because the o GETATTR(fsid,fileid,size,time_modify) Not executed because the
failure of the GETFH stops processing of the COMPOUND. failure of the GETFH stops processing of the COMPOUND.
Given the failure of the GETFH, the client has the job of determining Given the failure of the GETFH, the client has the job of determining
the root of the absent file system and where to find that file the root of the absent file system and where to find that file
system, i.e. the server and path relative to that server's root fh. system, i.e., the server and path relative to that server's root fh.
Note here that in this example, the client did not obtain filehandles Note here that in this example, the client did not obtain filehandles
and attribute information (e.g. fsid) for the intermediate and attribute information (e.g., fsid) for the intermediate
directories, so that it would not be sure where the absent file directories, so that it would not be sure where the absent file
system starts. It could be the case, for example, that /this/is/the system starts. It could be the case, for example, that /this/is/the
is the root of the moved file system and that the reason that the is the root of the moved file system and that the reason that the
lookup of "path" succeeded is that the file system was not absent on look up of "path" succeeded is that the file system was not absent on
that operation but was moved between the last LOOKUP and the GETFH that operation but was moved between the last LOOKUP and the GETFH
(since COMPOUND is not atomic). Even if we had the fsids for all of (since COMPOUND is not atomic). Even if we had the fsids for all of
the intermediate directories, we could have no way of knowing that the intermediate directories, we could have no way of knowing that
/this/is/the/path was the root of a new file system, since we don't /this/is/the/path was the root of a new file system, since we don't
yet have its fsid. yet have its fsid.
In order to get the necessary information, let us re-send the chain In order to get the necessary information, let us re-send the chain
of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we of LOOKUPs with GETFHs and GETATTRs to at least get the fsids so we
can be sure where the appropriate file system boundaries are. The can be sure where the appropriate file system boundaries are. The
client could choose to get fs_locations at the same time but in most client could choose to get fs_locations at the same time but in most
cases the client will have a good guess as to where file system cases the client will have a good guess as to where file system
boundaries are (because of where and where not NFS4ERR_MOVED was boundaries are (because of where NFS4ERR_MOVED was, and was not,
received) making fetching of fs_locations unnecessary. received) making fetching of fs_locations unnecessary.
OP01: PUTROOTFH --> NFS_OK OP01: PUTROOTFH --> NFS_OK
- Current fh is root of pseudo-fs. - Current fh is root of pseudo-fs.
OP02: GETATTR(fsid) --> NFS_OK OP02: GETATTR(fsid) --> NFS_OK
- Just for completeness. Normally, clients will know the fsid of - Just for completeness. Normally, clients will know the fsid of
the pseudo-fs as soon as they establish communication with a the pseudo-fs as soon as they establish communication with a
skipping to change at page 94, line 17 skipping to change at page 94, line 21
OP11: GETFH --> NFS_OK OP11: GETFH --> NFS_OK
- Current fh is for /this/is/the and is within pseudo-fs. - Current fh is for /this/is/the and is within pseudo-fs.
OP12: LOOKUP "path" --> NFS_OK OP12: LOOKUP "path" --> NFS_OK
- Current fh is for /this/is/the/path and is within a new, absent - Current fh is for /this/is/the/path and is within a new, absent
file system, but ... file system, but ...
- The client will never see the value of that fh - The client will never see the value of that fh.
OP13: GETATTR(fsid, fs_locations) --> NFS_OK OP13: GETATTR(fsid, fs_locations) --> NFS_OK
- We are getting the fsid to know where the file system boundaries - We are getting the fsid to know where the file system boundaries
are. In this operation the fsid will be different than that of are. In this operation, the fsid will be different than that of
the parent directory (which in turn was retrieved in OP10). Note the parent directory (which in turn was retrieved in OP10). Note
that the fsid we are given will not necessarily be preserved at that the fsid we are given will not necessarily be preserved at
the new location. That fsid might be different and in fact the the new location. That fsid might be different, and in fact the
fsid we have for this file system might be a valid fsid of a fsid we have for this file system might be a valid fsid of a
different file system on that new server. different file system on that new server.
- In this particular case, we are pretty sure anyway that what has - In this particular case, we are pretty sure anyway that what has
moved is /this/is/the/path rather than /this/is/the since we have moved is /this/is/the/path rather than /this/is/the since we have
the fsid of the latter and it is that of the pseudo-fs, which the fsid of the latter and it is that of the pseudo-fs, which
presumably cannot move. However, in other examples, we might not presumably cannot move. However, in other examples, we might not
have this kind of information to rely on (e.g. /this/is/the might have this kind of information to rely on (e.g., /this/is/the might
be a non-pseudo file system separate from /this/is/the/path), so be a non-pseudo file system separate from /this/is/the/path), so
we need to have another reliable source information on the we need to have other reliable source information on the boundary
boundary of the file system which is moved. If, for example, the of the file system that is moved. If, for example, the file
file system "/this/is" had moved we would have a case of migration system /this/is had moved, we would have a case of migration
rather than referral and once the boundaries of the migrated file rather than referral, and once the boundaries of the migrated file
system was clear we could fetch fs_locations. system was clear we could fetch fs_locations.
- We are fetching fs_locations because the fact that we got an - We are fetching fs_locations because the fact that we got an
NFS4ERR_MOVED at this point means that it most likely that this is NFS4ERR_MOVED at this point means that it is most likely that this
a referral and we need the destination. Even if it is the case is a referral and we need the destination. Even if it is the case
that "/this/is/the" is a file system which has migrated, we will that /this/is/the is a file system that has migrated, we will
still need the location information for that file system. still need the location information for that file system.
OP14: GETFH --> NFS4ERR_MOVED OP14: GETFH --> NFS4ERR_MOVED
- Fails because current fh is in an absent file system at the start - Fails because current fh is in an absent file system at the start
of the operation and the spec makes no exception for GETFH. Note of the operation, and the specification makes no exception for
that this means the server will never send the client a filehandle GETFH. Note that this means the server will never send the client
from within an absent file system. a filehandle from within an absent file system.
Given the above, the client knows where the root of the absent file Given the above, the client knows where the root of the absent file
system is (/this/is/the/path), by noting where the change of fsid system is (/this/is/the/path) by noting where the change of fsid
occurred (between "the" and "path"). The fs_locations attribute also occurred (between "the" and "path"). The fs_locations attribute also
gives the client the actual location of the absent file system, so gives the client the actual location of the absent file system, so
that the referral can proceed. The server gives the client the bare that the referral can proceed. The server gives the client the bare
minimum of information about the absent file system so that there minimum of information about the absent file system so that there
will be very little scope for problems of conflict between will be very little scope for problems of conflict between
information sent by the referring server and information of the file information sent by the referring server and information of the file
system's home. No filehandles and very few attributes are present on system's home. No filehandles and very few attributes are present on
the referring server and the client can treat those it receives as the referring server, and the client can treat those it receives as
basically transient information with the function of enabling the transient information with the function of enabling the referral.
referral.
7.8.2. Referral Example (READDIR) 7.8.2. Referral Example (READDIR)
Another context in which a client may encounter referrals is when it Another context in which a client may encounter referrals is when it
does a READDIR on directory in which some of the sub-directories are does a READDIR on a directory in which some of the sub-directories
the roots of absent file systems. are the roots of absent file systems.
Suppose such a directory is read as follows: Suppose such a directory is read as follows:
o PUTROOTFH o PUTROOTFH
o LOOKUP "this" o LOOKUP "this"
o LOOKUP "is" o LOOKUP "is"
o LOOKUP "the" o LOOKUP "the"
o READDIR (fsid, size, time_modify, mounted_on_fileid) o READDIR (fsid, size, time_modify, mounted_on_fileid)
In this case, because rdattr_error is not requested, fs_locations is In this case, because rdattr_error is not requested, fs_locations is
not requested, and some of attributes cannot be provided, the result not requested, and some of the attributes cannot be provided, the
will be an NFS4ERR_MOVED error on the READDIR, with the detailed result will be an NFS4ERR_MOVED error on the READDIR, with the
results as follows: detailed results as follows:
o PUTROOTFH --> NFS_OK. The current fh is at the root of the o PUTROOTFH --> NFS_OK. The current fh is at the root of the
pseudo-fs. pseudo-fs.
o LOOKUP "this" --> NFS_OK. The current fh is for /this and is o LOOKUP "this" --> NFS_OK. The current fh is for /this and is
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is o LOOKUP "is" --> NFS_OK. The current fh is for /this/is and is
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and
is within the pseudo-fs. is within the pseudo-fs.
o READDIR (fsid, size, time_modify, mounted_on_fileid) --> o READDIR (fsid, size, time_modify, mounted_on_fileid) -->
NFS4ERR_MOVED. Note that the same error would have been returned NFS4ERR_MOVED. Note that the same error would have been returned
if /this/is/the had migrated, when in fact it is because the if /this/is/the had migrated, but it is returned because the
directory contains the root of an absent file system. directory contains the root of an absent file system.
So now suppose that we re-send with rdattr_error: So now suppose that we re-send with rdattr_error:
o PUTROOTFH o PUTROOTFH
o LOOKUP "this" o LOOKUP "this"
o LOOKUP "is" o LOOKUP "is"
skipping to change at page 97, line 35 skipping to change at page 97, line 35
within the pseudo-fs. within the pseudo-fs.
o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and o LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the and
is within the pseudo-fs. is within the pseudo-fs.
o READDIR (rdattr_error, fs_locations, mounted_on_fileid, fsid, o READDIR (rdattr_error, fs_locations, mounted_on_fileid, fsid,
size, time_modify) --> NFS_OK. The attributes will be as shown size, time_modify) --> NFS_OK. The attributes will be as shown
below. below.
The attributes for the directory entry with the component named The attributes for the directory entry with the component named
"path" will only contain "path" will only contain:
o rdattr_error (value: NFS_OK) o rdattr_error (value: NFS_OK)
o fs_locations o fs_locations
o mounted_on_fileid (value: unique fileid within referring file o mounted_on_fileid (value: unique fileid within referring file
system) system)
o fsid (value: unique value within referring server) o fsid (value: unique value within referring server)
The attributes for entry "path" will not contain size or time_modify The attributes for entry "path" will not contain size or time_modify
because these attributes are not available within an absent file because these attributes are not available within an absent file
system. system.
7.9. The Attribute fs_locations 7.9. The Attribute fs_locations
The fs_locations attribute is structured in the following way: The fs_locations attribute is structured in the following way:
struct fs_location4 { struct fs_location4 {
utf8val_must server<>; utf8must server<>;
pathname4 rootpath; pathname4 rootpath;
}; };
struct fs_locations4 { struct fs_locations4 {
pathname4 fs_root; pathname4 fs_root;
fs_location4 locations<>; fs_location4 locations<>;
}; };
The fs_location4 data type is used to represent the location of a The fs_location4 data type is used to represent the location of a
file system by providing a server name and the path to the root of file system by providing a server name and the path to the root of
the file system within that server's namespace. When a set of the file system within that server's namespace. When a set of
servers have corresponding file systems at the same path within their servers have corresponding file systems at the same path within their
namespaces, an array of server names may be provided. An entry in namespaces, an array of server names may be provided. An entry in
the server array is a UTF-8 string and represents one of a the server array is a UTF-8 string and represents one of a
traditional DNS host name, IPv4 address, or IPv6 address, or an zero- traditional DNS host name, IPv4 address, IPv6 address, or an zero-
length string. A zero-length string SHOULD be used to indicate the length string. A zero-length string SHOULD be used to indicate the
current address being used for the RPC call. It is not a requirement current address being used for the RPC call. It is not a requirement
that all servers that share the same rootpath be listed in one that all servers that share the same rootpath be listed in one
fs_location4 instance. The array of server names is provided for fs_location4 instance. The array of server names is provided for
convenience. Servers that share the same rootpath may also be listed convenience. Servers that share the same rootpath may also be listed
in separate fs_location4 entries in the fs_locations attribute. in separate fs_location4 entries in the fs_locations attribute.
The fs_locations4 data type and fs_locations attribute contain an The fs_locations4 data type and fs_locations attribute contain an
array of such locations. Since the namespace of each server may be array of such locations. Since the namespace of each server may be
constructed differently, the "fs_root" field is provided. The path constructed differently, the "fs_root" field is provided. The path
represented by fs_root represents the location of the file system in represented by fs_root represents the location of the file system in
the current server's namespace, i.e. that of the server from which the current server's namespace, i.e., that of the server from which
the fs_locations attribute was obtained. The fs_root path is meant the fs_locations attribute was obtained. The fs_root path is meant
to aid the client by clearly referencing the root of the file system to aid the client by clearly referencing the root of the file system
whose locations are being reported, no matter what object within the whose locations are being reported, no matter what object within the
current file system the current filehandle designates. The fs_root current file system the current filehandle designates. The fs_root
is simply the pathname the client used to reach the object on the is simply the pathname the client used to reach the object on the
current server, the object being that the fs_locations attribute current server (i.e., the object to which the fs_locations attribute
applies to. applies).
When the fs_locations attribute is interrogated and there are no When the fs_locations attribute is interrogated and there are no
alternate file system locations, the server SHOULD return a zero- alternate file system locations, the server SHOULD return a zero-
length array of fs_location4 structures, together with a valid length array of fs_location4 structures, together with a valid
fs_root. fs_root.
As an example, suppose there is a replicated file system located at As an example, suppose there is a replicated file system located at
two servers (servA and servB). At servA, the file system is located two servers (servA and servB). At servA, the file system is located
at path "/a/b/c". At, servB the file system is located at path at path /a/b/c. At, servB the file system is located at path /x/y/z.
"/x/y/z". If the client were to obtain the fs_locations value for If the client were to obtain the fs_locations value for the directory
the directory at "/a/b/c/d", it might not necessarily know that the at /a/b/c/d, it might not necessarily know that the file system's
file system's root is located in servA's namespace at "/a/b/c". When root is located in servA's namespace at /a/b/c. When the client
the client switches to servB, it will need to determine that the switches to servB, it will need to determine that the directory it
directory it first referenced at servA is now represented by the path first referenced at servA is now represented by the path /x/y/z/d on
"/x/y/z/d" on servB. To facilitate this, the fs_locations attribute servB. To facilitate this, the fs_locations attribute provided by
provided by servA would have a fs_root value of "/a/b/c" and two servA would have an fs_root value of /a/b/c and two entries in
entries in fs_locations. One entry in fs_locations will be for fs_locations. One entry in fs_locations will be for itself (servA)
itself (servA) and the other will be for servB with a path of and the other will be for servB with a path of /x/y/z. With this
"/x/y/z". With this information, the client is able to substitute information, the client is able to substitute /x/y/z for the /a/b/c
"/x/y/z" for the "/a/b/c" at the beginning of its access path and at the beginning of its access path and construct /x/y/z/d to use for
construct "/x/y/z/d" to use for the new server. the new server.
Note that: there is no requirement that the number of components in Note that: there is no requirement that the number of components in
each rootpath be the same; there is no relation between the number of each rootpath be the same; there is no relation between the number of
components in rootpath or fs_root; and the none of the components in components in rootpath or fs_root, and none of the components in each
each rootpath and fs_root have to be the same. In the above example, rootpath and fs_root have to be the same. In the above example, we
we could have had a third element in the locations array, with server could have had a third element in the locations array, with server
equal to "servC", and rootpath equal to "/I/II", and a fourth element equal to "servC", and rootpath equal to "/I/II", and a fourth element
in locations with server equal to "servD", and rootpath equal to in locations with server equal to "servD" and rootpath equal to
"/aleph/beth/gimel/daleth/he". "/aleph/beth/gimel/daleth/he".
The relationship between fs_root to a rootpath is that the client The relationship between fs_root to a rootpath is that the client
replaces the pathname indicated in fs_root for the current server for replaces the pathname indicated in fs_root for the current server for
the substitute indicated in rootpath for the new server. the substitute indicated in rootpath for the new server.
For an example for a referred or migrated file system, suppose there For an example of a referred or migrated file system, suppose there
is a file system located at serv1. At serv1, the file system is is a file system located at serv1. At serv1, the file system is
located at "/az/buky/vedi/glagoli". The client finds that object at located at /az/buky/vedi/glagoli. The client finds that object at
"glagoli" has migrated (or is a referral). The client gets the glagoli has migrated (or is a referral). The client gets the
fs_locations attribute, which contains an fs_root of "/az/buky/vedi/ fs_locations attribute, which contains an fs_root of /az/buky/vedi/
glagoli", and one element in the locations array, with server equal glagoli, and one element in the locations array, with server equal to
to "serv2", and rootpath equal to "/izhitsa/fita". The client serv2, and rootpath equal to /izhitsa/fita. The client replaces /az/
replaces "/az/buky/vedi/glagoli" with "/izhitsa/fita", and uses the buky/vedi/glagoli with /izhitsa/fita, and uses the latter pathname on
latter pathname on "serv2". serv2.
Thus, the server MUST return an fs_root that is equal to the path the Thus, the server MUST return an fs_root that is equal to the path the
client used to reach the object the fs_locations attribute applies client used to reach the object to which the fs_locations attribute
to. Otherwise the client cannot determine the new path to use on the applies. Otherwise, the client cannot determine the new path to use
new server. on the new server.
7.9.1. Inferring Transition Modes 7.9.1. Inferring Transition Modes
When fs_locations is used, information about the specific locations When fs_locations is used, information about the specific locations
should be assumed based on the following rules. should be assumed based on the following rules.
The following rules are general and apply irrespective of the The following rules are general and apply irrespective of the
context. context.
o All listed file system instances should be considered as of the o All listed file system instances should be considered as of the
same _handle_ class, if and only if, the current fh_expire_type same handle class if and only if the current fh_expire_type
attribute does not include the FH4_VOL_MIGRATION bit. Note that attribute does not include the FH4_VOL_MIGRATION bit. Note that
in the case of referral, filehandle issues do not apply since in the case of referral, filehandle issues do not apply since
there can be no filehandles known within the current file system there can be no filehandles known within the current file system
nor is there any access to the fh_expire_type attribute on the nor is there any access to the fh_expire_type attribute on the
referring (absent) file system. referring (absent) file system.
o All listed file system instances should be considered as of the o All listed file system instances should be considered as of the
same _fileid_ class, if and only if, the fh_expire_type attribute same fileid class if and only if the fh_expire_type attribute
indicates persistent filehandles and does not include the indicates persistent filehandles and does not include the
FH4_VOL_MIGRATION bit. Note that in the case of referral, fileid FH4_VOL_MIGRATION bit. Note that in the case of referral, fileid
issues do not apply since there can be no fileids known within the issues do not apply since there can be no fileids known within the
referring (absent) file system nor is there any access to the referring (absent) file system nor is there any access to the
fh_expire_type attribute. fh_expire_type attribute.
o All file system instances servers should be considered as of o All file system instances servers should be considered as of
different _change_ classes. different change classes.
o All file system instances servers should be considered as of
different readdir classes.
For other class assignments, handling of file system transitions For other class assignments, handling of file system transitions
depends on the reasons for the transition: depends on the reasons for the transition:
o When the transition is due to migration, that is the client was o When the transition is due to migration, that is, the client was
directed to new file system after receiving an NFS4ERR_MOVED directed to a new file system after receiving an NFS4ERR_MOVED
error, the target should be treated as being of the same _write- error, the target should be treated as being of the same write-
verifier_ class as the source. verifier class as the source.
o When the transition is due to failover to another replica, that o When the transition is due to failover to another replica, that
is, the client selected another replica without receiving and is, the client selected another replica without receiving and
NFS4ERR_MOVED error, the target should be treated as being of a NFS4ERR_MOVED error, the target should be treated as being of a
different _write-verifier_ class from the source. different write-verifier class from the source.
The specific choices reflect typical implementation patterns for The specific choices reflect typical implementation patterns for
failover and controlled migration respectively. failover and controlled migration, respectively.
See Section 17 for a discussion on the recommendations for the See Section 17 for a discussion on the recommendations for the
security flavor to be used by any GETATTR operation that requests the security flavor to be used by any GETATTR operation that requests the
"fs_locations" attribute. "fs_locations" attribute.
8. NFS Server Name Space 8. NFS Server Name Space
8.1. Server Exports 8.1. Server Exports
On a UNIX server the name space describes all the files reachable by On a UNIX server the name space describes all the files reachable by
pathnames under the root directory or "/". On a Windows NT server pathnames under the root directory or "/". On a Windows NT server
the name space constitutes all the files on disks named by mapped the name space constitutes all the files on disks named by mapped
disk letters. NFS server administrators rarely make the entire disk letters. NFS server administrators rarely make the entire
server's filesystem name space available to NFS clients. More often server's filesystem name space available to NFS clients. More often
portions of the name space are made available via an "export" portions of the name space are made available via an "export"
feature. In previous versions of the NFS protocol, the root feature. In previous versions of the NFS protocol, the root
filehandle for each export is obtained through the MOUNT protocol; filehandle for each export is obtained through the MOUNT protocol;
skipping to change at page 105, line 40 skipping to change at page 105, line 43
of the client might have had on the server, as opposed to forcing the of the client might have had on the server, as opposed to forcing the
new client incarnation to wait for the leases to expire. Breaking new client incarnation to wait for the leases to expire. Breaking
the lease state amounts to the server removing all lock, share the lease state amounts to the server removing all lock, share
reservation, and, where the server is not supporting the reservation, and, where the server is not supporting the
CLAIM_DELEGATE_PREV claim type, all delegation state associated with CLAIM_DELEGATE_PREV claim type, all delegation state associated with
same client with the same identity. For discussion of delegation same client with the same identity. For discussion of delegation
state recovery, see Section 10.2.1. state recovery, see Section 10.2.1.
Client identification is encapsulated in the following structure: Client identification is encapsulated in the following structure:
struct SETCLIENTID4args { struct nfs_client_id4 {
nfs_client_id4 client; verifier4 verifier;
cb_client4 callback; opaque id<NFS4_OPAQUE_LIMIT>;
uint32_t callback_ident;
}; };
The first field, verifier is a client incarnation verifier that is The first field, verifier is a client incarnation verifier that is
used to detect client reboots. Only if the verifier is different used to detect client reboots. Only if the verifier is different
from that which the server has previously recorded the client (as from that which the server has previously recorded the client (as
identified by the second field of the structure, id) does the server identified by the second field of the structure, id) does the server
start the process of canceling the client's leased state. start the process of canceling the client's leased state.
The second field, id is a variable length string that uniquely The second field, id is a variable length string that uniquely
defines the client. defines the client.
skipping to change at page 113, line 30 skipping to change at page 113, line 36
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
the following errors: NFS4ERR_STALE_CLIENTID, NFS4ERR_STALE_STATEID, the following errors: NFS4ERR_STALE_CLIENTID, NFS4ERR_STALE_STATEID,
NFS4ERR_BAD_STATEID, NFS4ERR_BAD_SEQID, NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, NFS4ERR_BAD_SEQID, NFS4ERR_BADXDR,
NFS4ERR_RESOURCE, NFS4ERR_NOFILEHANDLE. NFS4ERR_RESOURCE, NFS4ERR_NOFILEHANDLE, NFS4ERR_LEASE_MOVED, or
NFS4ERR_MOVED.
9.1.6. Recovery from Replayed Requests 9.1.6. Recovery from Replayed Requests
As described above, the sequence number is per lock_owner. As long As described above, the sequence number is per lock_owner. As long
as the server maintains the last sequence number received and follows as the server maintains the last sequence number received and follows
the methods described above, there are no risks of a Byzantine router the methods described above, there are no risks of a Byzantine router
re-sending old requests. The server need only maintain the re-sending old requests. The server need only maintain the
(lock_owner, sequence number) state as long as there are open files (lock_owner, sequence number) state as long as there are open files
or closed files with locks outstanding. or closed files with locks outstanding.
skipping to change at page 114, line 26 skipping to change at page 114, line 33
returned to the client. returned to the client.
9.1.8. Use of Open Confirmation 9.1.8. Use of Open Confirmation
In the case that an OPEN is retransmitted and the lock_owner is being In the case that an OPEN is retransmitted and the lock_owner is being
used for the first time or the lock_owner state has been previously used for the first time or the lock_owner state has been previously
released by the server, the use of the OPEN_CONFIRM operation will released by the server, the use of the OPEN_CONFIRM operation will
prevent incorrect behavior. When the server observes the use of the prevent incorrect behavior. When the server observes the use of the
lock_owner for the first time, it will direct the client to perform lock_owner for the first time, it will direct the client to perform
the OPEN_CONFIRM for the corresponding OPEN. This sequence the OPEN_CONFIRM for the corresponding OPEN. This sequence
establishes the use of an lock_owner and associated sequence number. establishes the use of a lock_owner and associated sequence number.
Since the OPEN_CONFIRM sequence connects a new open_owner on the Since the OPEN_CONFIRM sequence connects a new open_owner on the
server with an existing open_owner on a client, the sequence number server with an existing open_owner on a client, the sequence number
may have any value. The OPEN_CONFIRM step assures the server that may have any value. The OPEN_CONFIRM step assures the server that
the value received is the correct one. (see Section 15.20 for further the value received is the correct one. (see Section 15.20 for further
details.) details.)
There are a number of situations in which the requirement to confirm There are a number of situations in which the requirement to confirm
an OPEN would pose difficulties for the client and server, in that an OPEN would pose difficulties for the client and server, in that
they would be prevented from acting in a timely fashion on they would be prevented from acting in a timely fashion on
information received, because that information would be provisional, information received, because that information would be provisional,
skipping to change at page 129, line 22 skipping to change at page 129, line 34
When responsibility for handling a given file system is transferred When responsibility for handling a given file system is transferred
to a new server (migration) or the client chooses to use an alternate to a new server (migration) or the client chooses to use an alternate
server (e.g., in response to server unresponsiveness) in the context server (e.g., in response to server unresponsiveness) in the context
of file system replication, the appropriate handling of state shared of file system replication, the appropriate handling of state shared
between the client and server (i.e., locks, leases, stateids, and between the client and server (i.e., locks, leases, stateids, and
clientids) is as described below. The handling differs between clientids) is as described below. The handling differs between
migration and replication. For related discussion of file server migration and replication. For related discussion of file server
state and recover of such see the sections under Section 9.6. state and recover of such see the sections under Section 9.6.
If server replica or a server immigrating a filesystem agrees to, or If a server replica or a server immigrating a filesystem agrees to,
is expected to, accept opaque values from the client that originated or is expected to, accept opaque values from the client that
from another server, then it is a wise implementation practice for originated from another server, then it is a wise implementation
the servers to encode the "opaque" values in network byte order. practice for the servers to encode the "opaque" values in network
This way, servers acting as replicas or immigrating filesystems will byte order. This way, servers acting as replicas or immigrating
be able to parse values like stateids, directory cookies, filesystems will be able to parse values like stateids, directory
filehandles, etc. even if their native byte order is different from cookies, filehandles, etc. even if their native byte order is
other servers cooperating in the replication and migration of the different from other servers cooperating in the replication and
filesystem. migration of the filesystem.
9.14.1. Migration and State 9.14.1. Migration and State
In the case of migration, the servers involved in the migration of a In the case of migration, the servers involved in the migration of a
filesystem SHOULD transfer all server state from the original to the filesystem SHOULD transfer all server state from the original to the
new server. This must be done in a way that is transparent to the new server. This must be done in a way that is transparent to the
client. This state transfer will ease the client's transition when a client. This state transfer will ease the client's transition when a
filesystem migration occurs. If the servers are successful in filesystem migration occurs. If the servers are successful in
transferring all state, the client will continue to use stateids transferring all state, the client will continue to use stateids
assigned by the original server. Therefore the new server must assigned by the original server. Therefore the new server must
skipping to change at page 130, line 11 skipping to change at page 130, line 23
server will typically have a different expiration time from those for server will typically have a different expiration time from those for
the same client, previously on the old server. To maintain the the same client, previously on the old server. To maintain the
property that all leases on a given server for a given client expire property that all leases on a given server for a given client expire
at the same time, the server should advance the expiration time to at the same time, the server should advance the expiration time to
the later of the leases being transferred or the leases already the later of the leases being transferred or the leases already
present. This allows the client to maintain lease renewal of both present. This allows the client to maintain lease renewal of both
classes without special effort. classes without special effort.
The servers may choose not to transfer the state information upon The servers may choose not to transfer the state information upon
migration. However, this choice is discouraged. In this case, when migration. However, this choice is discouraged. In this case, when
the client presents state information from the original server (e.g. the client presents state information from the original server (e.g.,
in a RENEW op or a READ op of zero length), the client must be in a RENEW op or a READ op of zero length), the client must be
prepared to receive either NFS4ERR_STALE_CLIENTID or prepared to receive either NFS4ERR_STALE_CLIENTID or
NFS4ERR_STALE_STATEID from the new server. The client should then NFS4ERR_STALE_STATEID from the new server. The client should then
recover its state information as it normally would in response to a recover its state information as it normally would in response to a
server failure. The new server must take care to allow for the server failure. The new server must take care to allow for the
recovery of state information as it would in the event of server recovery of state information as it would in the event of server
restart. restart.
A client SHOULD re-establish new callback information with the new A client SHOULD re-establish new callback information with the new
server as soon as possible, according to sequences described in server as soon as possible, according to sequences described in
skipping to change at page 131, line 6 skipping to change at page 131, line 18
In the case of lease renewal, the client may not be submitting In the case of lease renewal, the client may not be submitting
requests for a filesystem that has been migrated to another server. requests for a filesystem that has been migrated to another server.
This can occur because of the implicit lease renewal mechanism. The This can occur because of the implicit lease renewal mechanism. The
client renews leases for all filesystems when submitting a request to client renews leases for all filesystems when submitting a request to
any one filesystem at the server. any one filesystem at the server.
In order for the client to schedule renewal of leases that may have In order for the client to schedule renewal of leases that may have
been relocated to the new server, the client must find out about been relocated to the new server, the client must find out about
lease relocation before those leases expire. To accomplish this, all lease relocation before those leases expire. To accomplish this, all
operations which implicitly renew leases for a client (i.e., OPEN, operations which implicitly renew leases for a client (such as OPEN,
CLOSE, READ, WRITE, RENEW, LOCK, LOCKT, LOCKU), will return the error CLOSE, READ, WRITE, RENEW, LOCK, and others), will return the error
NFS4ERR_LEASE_MOVED if responsibility for any of the leases to be NFS4ERR_LEASE_MOVED if responsibility for any of the leases to be
renewed has been transferred to a new server. This condition will renewed has been transferred to a new server. This condition will
continue until the client receives an NFS4ERR_MOVED error and the continue until the client receives an NFS4ERR_MOVED error and the
server receives the subsequent GETATTR(fs_locations) for an access to server receives the subsequent GETATTR(fs_locations) for an access to
each filesystem for which a lease has been moved to a new server. each filesystem for which a lease has been moved to a new server. By
convention, the compound including the GETATTR(fs_locations) SHOULD
append a RENEW operation to permit the server to identify the client
doing the access.
When a client receives an NFS4ERR_LEASE_MOVED error, it should When a client receives an NFS4ERR_LEASE_MOVED error, it should
perform an operation on each filesystem associated with the server in perform an operation on each filesystem associated with the server in
question. When the client receives an NFS4ERR_MOVED error, the question. When the client receives an NFS4ERR_MOVED error, the
client can follow the normal process to obtain the new server client can follow the normal process to obtain the new server
information (through the fs_locations attribute) and perform renewal information (through the fs_locations attribute) and perform renewal
of those leases on the new server. If the server has not had state of those leases on the new server. If the server has not had state
transferred to it transparently, the client will receive either transferred to it transparently, the client will receive either
NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from the new server, NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from the new server,
as described above, and the client can then recover state information as described above, and the client can then recover state information
skipping to change at page 139, line 19 skipping to change at page 139, line 33
The data that is written to the server as a prerequisite to the The data that is written to the server as a prerequisite to the
unlocking of a region must be written, at the server, to stable unlocking of a region must be written, at the server, to stable
storage. The client may accomplish this either with synchronous storage. The client may accomplish this either with synchronous
writes or by following asynchronous writes with a COMMIT operation. writes or by following asynchronous writes with a COMMIT operation.
This is required because retransmission of the modified data after a This is required because retransmission of the modified data after a
server reboot might conflict with a lock held by another client. server reboot might conflict with a lock held by another client.
A client implementation may choose to accommodate applications which A client implementation may choose to accommodate applications which
use record locking in non-standard ways (e.g., using a record lock as use record locking in non-standard ways (e.g., using a record lock as
a global semaphore) by flushing to the server more data upon an LOCKU a global semaphore) by flushing to the server more data upon a LOCKU
than is covered by the locked range. This may include modified data than is covered by the locked range. This may include modified data
within files other than the one for which the unlocks are being done. within files other than the one for which the unlocks are being done.
In such cases, the client must not interfere with applications whose In such cases, the client must not interfere with applications whose
READs and WRITEs are being done only within the bounds of record READs and WRITEs are being done only within the bounds of record
locks which the application holds. For example, an application locks locks which the application holds. For example, an application locks
a single byte of a file and proceeds to write that single byte. A a single byte of a file and proceeds to write that single byte. A
client that chose to handle a LOCKU by flushing all modified data to client that chose to handle a LOCKU by flushing all modified data to
the server could validly write that single byte in response to an the server could validly write that single byte in response to an
unrelated unlock. However, it would not be valid to write the entire unrelated unlock. However, it would not be valid to write the entire
block in which that single written byte was located since it includes block in which that single written byte was located since it includes
skipping to change at page 159, line 50 skipping to change at page 160, line 17
* adding bits to flag fields such as new attributes to * adding bits to flag fields such as new attributes to
GETATTR's bitmap4 data type GETATTR's bitmap4 data type
* adding bits to existing attributes like ACLs that have flag * adding bits to existing attributes like ACLs that have flag
words words
* extending enumerated types (including NFS4ERR_*) with new * extending enumerated types (including NFS4ERR_*) with new
values values
4. Minor versions may not modify the structure of existing 4. Minor versions must not modify the structure of existing
attributes. attributes.
5. Minor versions may not delete operations. 5. Minor versions must not delete operations.
This prevents the potential reuse of a particular operation This prevents the potential reuse of a particular operation
"slot" in a future minor version. "slot" in a future minor version.
6. Minor versions may not delete attributes. 6. Minor versions must not delete attributes.
7. Minor versions may not delete flag bits or enumeration values. 7. Minor versions must not delete flag bits or enumeration values.
8. Minor versions may declare an operation as mandatory to NOT 8. Minor versions may declare an operation MUST NOT be implement.
implement.
Specifying an operation as "mandatory to not implement" is Specifying that an operation MUST NOT be implemented is
equivalent to obsoleting an operation. For the client, it means equivalent to obsoleting an operation. For the client, it means
that the operation should not be sent to the server. For the that the operation MUST NOT be sent to the server. For the
server, an NFS error can be returned as opposed to "dropping" server, an NFS error can be returned as opposed to "dropping"
the request as an XDR decode error. This approach allows for the request as an XDR decode error. This approach allows for
the obsolescence of an operation while maintaining its structure the obsolescence of an operation while maintaining its structure
so that a future minor version can reintroduce the operation. so that a future minor version can reintroduce the operation.
1. Minor versions may declare attributes mandatory to NOT 1. Minor versions may declare that an attribute MUST NOT be
implement. implemented.
2. Minor versions may declare flag bits or enumeration values 2. Minor versions may declare that a flag bit or enumeration
as mandatory to NOT implement. value MUST NOT be implemented.
9. Minor versions may downgrade features from mandatory to 9. Minor versions may downgrade features from REQUIRED to
recommended, or recommended to optional. RECOMMENDED, or RECOMMENDED to OPTIONAL.
10. Minor versions may upgrade features from optional to recommended 10. Minor versions may upgrade features from OPTIONAL to RECOMMENDED
or recommended to mandatory. or RECOMMENDED to REQUIRED.
11. A client and server that support minor version X must support 11. A client and server that support minor version X SHOULD support
minor versions 0 (zero) through X-1 as well. minor versions 0 (zero) through X-1 as well.
12. No new features may be introduced as mandatory in a minor 12. Except for infrastructural changes, no new features may be
version. introduced as REQUIRED in a minor version.
This rule allows for the introduction of new functionality and This rule allows for the introduction of new functionality and
forces the use of implementation experience before designating a forces the use of implementation experience before designating a
feature as mandatory. feature as REQUIRED. On the other hand, some classes of
features are infrastructural and have broad effects. Allowing
such features to not be REQUIRED complicates implementation of
the minor version.
13. A client MUST NOT attempt to use a stateid, filehandle, or 13. A client MUST NOT attempt to use a stateid, filehandle, or
similar returned object from the COMPOUND procedure with minor similar returned object from the COMPOUND procedure with minor
version X for another COMPOUND procedure with minor version Y, version X for another COMPOUND procedure with minor version Y,
where X != Y. where X != Y.
12. Internationalization 12. Internationalization
This chapter describes the string-handling aspects of the NFS version This chapter describes the string-handling aspects of the NFS version
4 protocol, and how they address issues related to 4 protocol, and how they address issues related to
skipping to change at page 161, line 45 skipping to change at page 162, line 12
for the implementation to allow files created by other protocols and for the implementation to allow files created by other protocols and
by local operations on the file system to be accessed using NFS by local operations on the file system to be accessed using NFS
version 4 as well. version 4 as well.
It also needs to be understood that a considerable portion of file It also needs to be understood that a considerable portion of file
name processing will occur within the implementation of the file name processing will occur within the implementation of the file
system rather than within the limits of the NFS version 4 server system rather than within the limits of the NFS version 4 server
implementation per se. As a result, cetain aspects of name implementation per se. As a result, cetain aspects of name
processing may change as the locus of processing moves from file processing may change as the locus of processing moves from file
system to file system. As a result of these factors, the protocol system to file system. As a result of these factors, the protocol
does not enforce uniformity of processing NFS version 4 server cannot enforce uniformity of name-related processing upon NFS version
requests on the server as a whole. Because the server interacts with 4 server requests on the server as a whole. Because the server
existing file system implementations, the same server handling will interacts with existing file system implementations, the same server
produce different behavior when interacting with different file handling will produce different behavior when interacting with
system implementations. To attempt to require uniform behavior, and different file system implementations. To attempt to require uniform
treat the the protocol server and the file system as a unified behavior, and treat the the protocol server and the file system as a
application, would considerably limit the usefulness of the protocol. unified application, would considerably limit the usefulness of the
protocol.
12.1. Use of UTF-8 12.1. Use of UTF-8
As mentioned above, UTF-8 is used as a convenient way to encode As mentioned above, UTF-8 is used as a convenient way to encode
Unicode which allows clients that have no internationalization Unicode which allows clients that have no internationalization
requirements to avoid these issues since the mapping of ASCII names requirements to avoid these issues since the mapping of ASCII names
to UTF-8 is the identity. to UTF-8 is the identity.
12.1.1. Relation to Stringprep 12.1.1. Relation to Stringprep
skipping to change at page 162, line 27 skipping to change at page 162, line 43
in ways that make sense for typical users throughout the world." A in ways that make sense for typical users throughout the world." A
protocol conforming to this framework must define a profile of protocol conforming to this framework must define a profile of
stringprep "in order to fully specify the processing options." NFS stringprep "in order to fully specify the processing options." NFS
version 4, while it does make normative references to stringprep and version 4, while it does make normative references to stringprep and
uses elements of that framework, it does not, for reasons that are uses elements of that framework, it does not, for reasons that are
explained below, conform to that framework, for all of the strings explained below, conform to that framework, for all of the strings
that are used within it. that are used within it.
In addition to some specific issues which have caused stringprep to In addition to some specific issues which have caused stringprep to
add confusion in handling certain characters for certain languages, add confusion in handling certain characters for certain languages,
there are a number of reasons why stringprep profiles are not there are a number of general reasons why stringprep profiles are not
suitable for describing NFS version 4. suitable for describing NFS version 4.
o Restricting the character repertoire to Unicode 3.2, as required o Restricting the character repertoire to Unicode 3.2, as required
by stringprep is unduly constricting. by stringprep is unduly constricting.
o Many of the character tables in stringprep are inappropriate o Many of the character tables in stringprep are inappropriate
because of this limited character repertoire, so that normative because of this limited character repertoire, so that normative
reference to stringprep is not desirable in many case and instead, reference to stringprep is not desirable in many case and instead,
we allow more flexibility in the definition of case mapping we allow more flexibility in the definition of case mapping
tables. tables.
o Because of the presence of different file systems, the specifics o Because of the presence of different file systems, the specifics
of processing are not fully defined and some aspects that are are of processing are not fully defined and some aspects that are are
RECOMMENDED, rather than REQUIRED. RECOMMENDED, rather than REQUIRED.
Despite these issues, in many cases the general structure of Despite these issues, in many cases the general structure of
stringprep profiles, consisting of sections which deal with the stringprep profiles, consisting of sections which deal with the
applicability of the description, the character repertoire, charcter applicability of the description, the character repertoire, charcter
mapping, normalization, prohibited characters, and issues of the mapping, normalization, prohibited characters, and issues of the
handling (i.e. possible prohibition) of bidirectional strings, is a handling (i.e., possible prohibition) of bidirectional strings, is a
convenient way to describe the string handling which is needed and convenient way to describe the string handling which is needed and
will be used where appropriate. will be used where appropriate.
12.1.2. Normalization, Equivalence, and Confusability 12.1.2. Normalization, Equivalence, and Confusability
Unicode has defined several equivalence relationships among the set Unicode has defined several equivalence relationships among the set
of possible strings. Understanding the nature and purpose of these of possible strings. Understanding the nature and purpose of these
equivalence relations is important to understand the handling of equivalence relations is important to understand the handling of
unicode strings within NFS version 4. Unicode strings within NFS version 4.
o Some string pairs are thought as only differing in the way accents Some string pairs are thought as only differing in the way accents
and other diacritics are encoded. Such string pairs are called and other diacritics are encoded, as illustrated in the examples
"canonically equivalent". For example, the character LATIN SMALL below. Such string pairs are called "canonically equivalent".
LETTER E WITH ACUTE (U+00E9) is defined as equivalent to the
Such equivalence can occur when there are precomposed characters,
as an alternative to encoding a base character in addition to a
combining accent. For example, the character LATIN SMALL LETTER E
WITH ACUTE (U+00E9) is defined as canonically equivalent to the
string consisting of LATIN SMALL LETTER E followed by COMBINING string consisting of LATIN SMALL LETTER E followed by COMBINING
ACUTE ACCENT (U+0065, U+0301). ACUTE ACCENT (U+0065, U+0301).
o Additionally there is an equvalence relation of "compatibility When multiple combining diacritics are present, differences in the
equivalence". Two canonically equivalent strings are necessarily ordering are not reflected in resulting display and the strings
compatibility equivalent, although not the converse. An example are defined as canonically equivalent. For example, the string
of compatibility equivalent strings which are not canonically consisting of LATIN SMALL LETTER Q, COMBINING ACUTE ACCENT,
equivalent are GREEK CAPITAL LETTER OMEGA (U+03A9) and OHM SIGN COMBINING GRAVE ACCENT (U+0071, U+0301, U+0300) is canonically
(U+2129). These are identical in appearance while other quivalent to the string consisting of LATIN SMALL LETTER Q,
compatibility equivalent strings are not. Another example would COMBINING GRAVE ACCENT, COMBINING ACUTE ACCENT (U+0071, U+0300,
be "x2" and the two character string denoting x-squared which are U+0301)
clearly differnt in appearance although compatibility equivalent
and not canonically equivalent. These have Unicode encodings When both situations are present, the number of canonically
LATIN SMALL LETTER X, DIGIT TWO (U+0078, U+0032) and LATIN SMALL equivalent strings can be greater. Thus, the following strings
LETTER X, SUPERSCRIPT TWO (U+0078, U+00B2), are all canonically equivalent:
LATIN SMALL LETTER E, COMBINING MACRON, ACCENT, COMBINING ACUTE
ACCENT (U+0xxx, U+0304, U+0301)
LATIN SMALL LETTER E, COMBINING ACUTE ACCENT, COMBINING MACRON
(U+0xxx, U+0301, U+0304)
LATIN SMALL LETTER E WITH MACRON, COMBINING ACUTE ACCENT
(U+011E, U+0301)
LATIN SMALL LETTER E WITH ACUTE, COMBINING MACRON (U+00E9,
U+0304)
LATIN SMALL LETTER E WITH MACRON AND ACUTE (U+1E16)
Additionally there is an equivalence relation of "compatibility
equivalence". Two canonically equivalent strings are necessarily
compatibility equivalent, although not the converse. An example of
compatibility equivalent strings which are not canonically equivalent
are GREEK CAPITAL LETTER OMEGA (U+03A9) and OHM SIGN (U+2129). These
are identical in appearance while other compatibility equivalent
strings are not. Another example would be "x2" and the two character
string denoting x-squared which are clearly differnt in appearance
although compatibility equivalent and not canonically equivalent.
These have Unicode encodings LATIN SMALL LETTER X, DIGIT TWO (U+0078,
U+0032) and LATIN SMALL LETTER X, SUPERSCRIPT TWO (U+0078, U+00B2),
One way to deal with these equivalence relations is via One way to deal with these equivalence relations is via
normalization. A normalization form maps all strings to correspond normalization. A normalization form maps all strings to a
normalized string in such a fashion that all strings that are correspondig normalized string in such a fashion that all strings
equivalent (canonically or compatibly, depending on the form) are that are equivalent (canonically or compatibly, depending on the
mapped to the same value. Thus the image of the mapping is a subset form) are mapped to the same value. Thus the image of the mapping is
of Unicode strings conceived as the representives of the equivalence a subset of Unicode strings conceived as the representives of the
classes defined by the chosed equivalence relation. equivalence classes defined by the chosen equivalence relation.
In the NFS version 4 protocol, handling of issues related to In the NFS version 4 protocol, handling of issues related to
internationalization with regard to normalization follows one of two internationalization with regard to normalization follows one of two
basic patterns: basic patterns:
o For strings whose function is related to other internet standards, o For strings whose function is related to other internet standards,
such as server and domain naming, the normalization form defined such as server and domain naming, the normalization form defined
by the appropriate internet standards is used. For server and by the appropriate internet standards is used. For server and
domain naming, this involves normalization form NKFC as specified domain naming, this involves normalization form NFKC as specified
in [10] in [10]
o For other strings, particular those passed by the server to file o For other strings, particular those passed by the server to file
system implementations, normalization requirements are the system implementations, normalization requirements are the
province of the file system and the job of this specification is province of the file system and the job of this specification is
not to specify a particular form but to make sure that not to specify a particular form but to make sure that
interoperability is maximmized, even when clients and server-based interoperability is maximmized, even when clients and server-based
file systems may have different preferences. file systems have different preferences.
A related but distinct issue concerns string confusability. This can A related but distinct issue concerns string confusability. This can
occur when two strings (including single-charcter strings) having a occur when two strings (including single-charcter strings) having a
similar appearance. There have been attempts to define uniform similar appearance. There have been attempts to define uniform
processing in an attempt to avoid such confusion (see stringprep [9]) processing in an attempt to avoid such confusion (see stringprep [9])
but the results have often added to confusion. but the results have often added confusion.
Some examples of possible confusions and proposed processing intended Some examples of possible confusions and proposed processing intended
to reduce/avoid confusions: to reduce/avoid confusions:
o Deletion of characters supposed to be invisible and appropriately o Deletion of characters believed to be invisible and appropriately
ignored, justifying their deletion, including, WORD JOINER ignored, justifying their deletion, including, WORD JOINER
(U+2060), and the ZERO WIDTH SPACE (U+200B). (U+2060), and the ZERO WIDTH SPACE (U+200B).
o Deletion of characters supposed to not bear semantics and only o Deletion of characters supposed to not bear semantics and only
affect glyph choice, including the ZERO WIDTH NON-JOINER (U+200C) affect glyph choice, including the ZERO WIDTH NON-JOINER (U+200C)
and the ZERO WIDTH JOINER (U+200D), where the deletion turns out and the ZERO WIDTH JOINER (U+200D), where the deletion turns out
to be a problem for Farsi speakers. to be a problem for Farsi speakers.
o Prohibition of space characters such as the EM SPACE (U+2003), the o Prohibition of space characters such as the EM SPACE (U+2003), the
EN SPACE (U+2002), and the THIN SPACE (U+2009). EN SPACE (U+2002), and the THIN SPACE (U+2009).
skipping to change at page 165, line 8 skipping to change at page 166, line 4
o For other strings, particularly those passed by the server to file o For other strings, particularly those passed by the server to file
system implementations, any such preparation requirements system implementations, any such preparation requirements
including the choice of how, or whether to address the including the choice of how, or whether to address the
confusability issue, are the responsibility of the file system to confusability issue, are the responsibility of the file system to
define, and for this specification to try to add its own set would define, and for this specification to try to add its own set would
add unacceptably to complexity, and make many files accessible add unacceptably to complexity, and make many files accessible
locally and by other remote file access protocols, inaccessible by locally and by other remote file access protocols, inaccessible by
NFS version 4. This specification defines how the protocol NFS version 4. This specification defines how the protocol
maximizes interoperability in the face of different file system maximizes interoperability in the face of different file system
implementations. implementations . NFS version 4 does allow file systems to map
and to reject characters, including those likely to result in
NFS version 4 does allow file systems to map and to reject confusion, since file systems may choose to do such things. It
characters, including those likely to result in confusion, since defines what the client will see in such cases, in order to limit
file systems may choose to do such things. It defines what the problems that can arise when a file name is created and it appears
client will see in such cases, in order to limit problems that can to have a different name from the one it is assigned when the name
arise when a file name is created and it appears to have a is created.
different name from the one it is assigned when the name is
created.
12.2. String Type Overview 12.2. String Type Overview
12.2.1. Overall String Class Divisions 12.2.1. Overall String Class Divisions
NFS version 4 has to deal with with a large set of diffreent types of NFS version 4 has to deal with a large set of diffreent types of
strings and because of the different role of each, strings and because of the different role of each,
internationalization issues will be different for each: internationalization issues will be different for each:
o For some types of strings, the fundamental internationalization- o For some types of strings, the fundamental internationalization-
related decisions are the province of the file system or the related decisions are the province of the file system or the
security-handling functions of the server and the protocol's job security-handling functions of the server and the protocol's job
is to establish the rules under which file systems and servers are is to establish the rules under which file systems and servers are
allowed to exercise this freedom, to avoid adding to confusion. allowed to exercise this freedom, to avoid adding to confusion.
o In other cases, the fundamental internationalization issues are o In other cases, the fundamental internationalization issues are
the responsibility of other IETF groups and our jobis simply to the responsibility of other IETF groups and our jobis simply to
reference those and perhaps make a few choices as to how they are reference those and perhaps make a few choices as to how they are
to be used (e.g. U-labels vs. A-labels). to be used (e.g., U-labels vs. A-labels).
o There are also cases in which a string has a small amount of NFS o There are also cases in which a string has a small amount of NFS
version 4 processing which results in one or more strings being version 4 processing which results in one or more strings being
referred to one of the other categories. referred to one of the other categories.
We will divide strings to be dealt with into the following classes: We will divide strings to be dealt with into the following classes:
MIX indicating that there is small amount of preparatory processing MIX indicating that there is small amount of preparatory processing
that either picks an appropriate modes of internationalization that either picks an internationalization hadling mode or divides
handling or divides the string into a set of (two) strings with a the string into a set of (two) strings with a different mode
different mode internationalization handling for each. The internationalization handling for each. The details are discussed
details are discussed in the section "Types with Pre-processing to in the section "Types with Pre-processing to Resolve Mixture
Resolve Mixture Issues". Issues".
NIP indicating that, for various reasons, there is no need for NIP indicating that, for various reasons, there is no need for
internationalization-specific processing to be performed. The internationalization-specific processing to be performed. The
specifics of the various string types handled in this way are specifics of the various string types handled in this way are
described in the section "String Types without described in the section "String Types without
Internationalization Processing". Internationalization Processing".
INET indicating that the string needs to be processed in a fashion INET indicating that the string needs to be processed in a fashion
is goverened by non-NFS-specific internet specifications. The goverened by non-NFS-specific internet specifications. The
details are discussed in the section "Types with Processing details are discussed in the section "Types with Processing
Defined by Other Internet Areas". Defined by Other Internet Areas".
NFS indicating that the string needs to be processed in a fashion is NFS indicating that the string needs to be processed in a fashion
goverened by NFSv4-specific consideration. The primary focus is governed by NFSv4-specific considerations. The primary focus is
on enabling flexibility for the various file systems to be on enabling flexibility for the various file systems to be
accessed and is described in the section "String Types with NFS- accessed and is described in the section "String Types with NFS-
specific Processing". specific Processing".
12.2.2. Divisions by Typedef Parent types 12.2.2. Divisions by Typedef Parent types
There are a number of different string types within NFS version 4 and There are a number of different string types within NFS version 4 and
internationalization handling will be different for different types internationalization handling will be different for different types
of strings. Each the types will be in one of four groups based on of strings. Each the types will be in one of four groups based on
the parent type that specifies the nature of its relationship to utf8 the parent type that specifies the nature of its relationship to utf8
and ascii. and ascii.
utf8_should/SHOULD: indicating that strings of this type should be utf8_should/USHOULD: indicating that strings of this type SHOULD be
UTF-8 but clients and servers will not check for valid UTF-8 UTF-8 but clients and servers will not check for valid UTF-8
encoding. encoding.
utf8val_should/VSHOULD: indicating that strings of this type should utf8val_should/UVSHOULD: indicating that strings of this type SHOULD
be and generally will be in the form of the UTF-8 encoding of be and generally will be in the form of the UTF-8 encoding of
Unicode. Strings in most cases will be checked by the server for Unicode. Strings in most cases will be checked by the server for
valid UTF-8 but for certain file systems, such checking may be valid UTF-8 but for certain file systems, such checking may be
inhibited. inhibited.
utf8val_must/VMUST: indicating that strings of this type must be in utf8val_must/UVMUST: indicating that strings of this type MUST be in
the form of the UTF-8 encoding of Unicode. Strings will be the form of the UTF-8 encoding of Unicode. Strings will be
checked by the server for valid UTF-8 and the server should ensure checked by the server for valid UTF-8 and the server SHOULD ensure
that when sent to the client, they are valid UTF-8. that when sent to the client, they are valid UTF-8.
ascii_must/ASCII: indicating that strings of this type must be pure ascii_must/ASCII: indicating that strings of this type MUST be pure
ASCII, and thus automatically UTF-8. The processing of these ASCII, and thus automatically UTF-8. The processing of these
string must ensure that they are only have ASCII characters but string must ensure that they are only have ASCII characters but
this need not be a separate step if any normally required check this need not be a separate step if any normally required check
for validity inherently assures that only ASCII characters are for validity inherently assures that only ASCII characters are
present. present.
In those cases where UTF-8 is not required, USHOULD and UVSHOULD, and
strings that are not valid UTF-8 are received and accepted, the
receiver MUST NOT modify the strings. For example, setting
particular bits such as the high-order bit to zero MUST NOT be done.
12.2.3. Individual Types and Their Handling 12.2.3. Individual Types and Their Handling
The first table outlines the handling for the primary string types, The first table outlines the handling for the primary string types,
i.e. those not derived as a prefix or a suffix from a mixture type. i.e., those not derived as a prefix or a suffix from a mixture type.
+-----------------+---------+-------+-------------------------------+ +-----------------+----------+-------+------------------------------+
| Type | Parent | Class | Explanation | | Type | Parent | Class | Explanation |
+-----------------+---------+-------+-------------------------------+ +-----------------+----------+-------+------------------------------+
| comptag4 | SHOULD | NIP | Should be utf8 but no | | comptag4 | USHOULD | NIP | Should be utf8 but no |
| | | | validation by server or | | | | | validation by server or |
| | | | client is to be done. | | | | | client is to be done. |
| component4 | VSHOULD | NFS | Should be utf8 but clients | | component4 | UVSHOULD | NFS | Should be utf8 but clients |
| | | | may need to access file | | | | | may need to access file |
| | | | systems with a different name | | | | | systems with a different |
| | | | structure. files systems with | | | | | name structure, such as file |
| | | | non-utf8 names. | | | | | systems that have non-utf8 |
| linktext4 | VSHOULD | NFS | Should be utf8 since text may | | | | | names. |
| | | | include name components. | | linktext4 | UVSHOULD | NFS | Should be utf8 since text |
| | | | Because of the need to access | | | | | may include name components. |
| | | | existing file systems, this | | | | | Because of the need to |
| | | | check may be inhibited. | | | | | access existing file |
| fattr4_mimetype | ASCII | NIP | All mime types are ascii so | | | | | systems, this check may be |
| | | | no specific utf8 processing | | | | | inhibited. |
| | | | is required, given that you | | fattr4_mimetype | ASCII | NIP | All mime types are ascii so |
| | | | are comparing to that list. | | | | | no specific utf8 processing |
+-----------------+---------+-------+-------------------------------+ | | | | is required, given that you |
| | | | are comparing to that list. |
+-----------------+----------+-------+------------------------------+
Table 5 Table 5
There are a number of string types that are compound in that they may There are a number of string types that are subject to preliminary
consist of multiple conjoined strings with different utf8-related processing. This processing may take the form either of selecting
processing for each. one of two possible forms based on the string contents or it in may
consist of dividing the string into multiple conjoined strings each
with different utf8-related processing.
+---------+--------+-------+----------------------------------------+ +---------+--------+-------+----------------------------------------+
| Type | Parent | Class | Explanation | | Type | Parent | Class | Explanation |
+---------+--------+-------+----------------------------------------+ +---------+--------+-------+----------------------------------------+
| prin4 | VMUST | MIX | Consists of two parts separated by an | | prin4 | UVMUST | MIX | Consists of two parts separated by an |
| | | | at-sign, a prinpfx4 and a prinsfx4. | | | | | at-sign, a prinpfx4 and a prinsfx4. |
| | | | These are described in the next table. | | | | | These are described in the next table. |
| server4 | VMUST | MIX | Is either an IP address (serveraddr4) | | server4 | UVMUST | MIX | Is either an IP address (serveraddr4) |
| | | | which has to be pure ascii or a server | | | | | which has to be pure ascii or a server |
| | | | name svrname4, which is described | | | | | name svrname4, which is described |
| | | | immediately below. | | | | | immediately below. |
+---------+--------+-------+----------------------------------------+ +---------+--------+-------+----------------------------------------+
Table 6 Table 6
The last table describes the components of the compound types The last table describes the components of the compound types
described above. described above.
+----------+-------+------+-----------------------------------------+ +----------+--------+------+----------------------------------------+
| Type | Class | Def | Explanation | | Type | Class | Def | Explanation |
+----------+-------+------+-----------------------------------------+ +----------+--------+------+----------------------------------------+
| svraddr4 | ASCII | NIP | Server as IP address, whether IPv4 or | | svraddr4 | ASCII | NIP | Server as IP address, whether IPv4 or |
| | | | IPv6, | | | | | IPv6. |
| svrname4 | VMUST | INET | Server name as returned by server. Not | | svrname4 | UVMUST | INET | Server name as returned by server. |
| | | | sent by client, except in | | | | | Not sent by client, except in |
| | | | VERIFY/NVERIFY. | | | | | VERIFY/NVERIFY. |
| prinsfx4 | VMUST | INET | Suffix part of principal, in the form | | prinsfx4 | UVMUST | INET | Suffix part of principal, in the form |
| | | | of a domain name. | | | | | of a domain name. |
| prinpfx4 | VMUST | NFS | Must match one of a list of valid users | | prinpfx4 | UVMUST | NFS | Must match one of a list of valid |
| | | | or groups for that particular domain. | | | | | users or groups for that particular |
+----------+-------+------+-----------------------------------------+ | | | | domain. |
+----------+--------+------+----------------------------------------+
Table 7 Table 7
12.3. Errors Related to Strings 12.3. Errors Related to Strings
When the client sends an invalid UTF-8 string in a context in which When the client sends an invalid UTF-8 string in a context in which
UTF-8 is required, the server MUST return an NFS4ERR_INVAL error. UTF-8 is REQUIRED, the server MUST return an NFS4ERR_INVAL error.
When the client sends an invalid UTF-8 string in a context in which Within the framework of the previous section, this applies to strings
UTF-8 is recommended, the server SHOULD return an NFS4ERR_INVAL whose type is defined as utf8val_must or ascii_must. When the client
error. These situations apply to cases in which inappropriate sends an invalid UTF-8 string in a context in which UTF-8 is
prefixes are detected and where the count includes trailing bytes RECOMMENDED and the server should test for UTF-8, the server SHOULD
that do not constitute a full UCS character. return an NFS4ERR_INVAL error. Within the framework of the previous
section, this applies to strings whose type is defined as
utf8val_should. These situations apply to cases in which
inappropriate prefixes are detected and where the count includes
trailing bytes that do not constitute a full UCS character.
Where the client supplied string is valid UTF-8 but contains Where the client-supplied string is valid UTF-8 but contains
characters that are not supported by the server file system as a characters that are not supported by the server file system as a
value for that string (e.g., names containing characters that have value for that string (e.g., names containing characters that have
more than two octets on a file system that supports UCS-2 characters more than two octets on a file system that supports UCS-2 characters
only, file name components containing slashes on file systems that do only, file name components containing slashes on file systems that do
not allow them in filename file name components), the server should not allow them in file name components), the server MUST return an
MUST return an NFS4ERR_BADCHAR error. NFS4ERR_BADCHAR error.
Where a UTF-8 string is used as a file name component, and the file Where a UTF-8 string is used as a file name component, and the file
system, while supporting all of the characters within the name, does system, while supporting all of the characters within the name, does
not allow that particular name to be used, the server should return not allow that particular name to be used, the server should return
the error NFS4ERR_BADNAME. This includes file system prohibitions of the error NFS4ERR_BADNAME. This includes file system prohibitions of
"." and ".." as file names for certain operations, and other such "." and ".." as file names for certain operations, and other such
similar constraints. It does not include use of strings with non- similar constraints. It does not include use of strings with non-
preferred normalization modes. preferred normalization modes.
Where a UTF-8 string is used as a file name component, the file Where a UTF-8 string is used as a file name component, the file
system implementation MUST NOT return NFS4ERR_BADNAME, simply due to system implementation MUST NOT return NFS4ERR_BADNAME, simply due to
a normalization mismatch. In such cases the implementation MAY a normalization mismatch. In such cases the implementation SHOULD
convert the string to its own preferred normalization mode before convert the string to its own preferred normalization mode before
performing the operation. As a result, a client cannot assume that a performing the operation. As a result, a client cannot assume that a
file created with a name it specifies will have that name when the file created with a name it specifies will have that name when the
directory is read. It may have instead, the name converted to the directory is read. It may have instead, the name converted to the
file system's preferred normalization form. file system's preferred normalization form.
Where a UTF-8 string is used as other than a file name component and Where a UTF-8 string is used as other than as file name component (or
the string does not meet the normalization requirements specified for as symbolic link text) and the string does not meet the normalization
it, the error NFS4ERR_INVAL is returned. requirements specified for it, the error NFS4ERR_INVAL is returned.
12.4. Types with Pre-processing to Resolve Mixture Issues 12.4. Types with Pre-processing to Resolve Mixture Issues
12.4.1. Processing of Principal Strings 12.4.1. Processing of Principal Strings
Strings denoting principals (users or groups) MUST be UTF-8 but since Strings denoting principals (users or groups) MUST be UTF-8 but since
they consist of a principal prefix, an at-sign, and a domain, all they consist of a principal prefix, an at-sign, and a domain, all
three of which either are checked for being UTF-8, or inherently are three of which either are checked for being UTF-8, or inherently are
UTF-8, checking the string as a whole for being UTF-8 is not UTF-8, checking the string as a whole for being UTF-8 is not
required. Although a server implementation may choose to make this required. Although a server implementation may choose to make this
check on the string as whole, for example in converting it to check on the string as whole, for example in converting it to
Unicode, the description within this document, will reflect a Unicode, the description within this document, will reflect a
processing model in which such checking happens after the division processing model in which such checking happens after the division
into a principal prefix and suffix, the latter being in the form of a into a principal prefix and suffix, the latter being in the form of a
domain name. domain name.
The string should be scanned for at-signs. If there is more that one The string should be scanned for at-signs. If there is more that one
at-sign, the string is considered invalid. For cases in which there at-sign, the string is considered invalid. For cases in which there
are no at-signs or the at-sign appears at the start of end of the are no at-signs or the at-sign appears at the start or end of the
string see Interpreting owner and owner_group Otherwise, the portion string see Interpreting owner and owner_group. Otherwise, the
before the at-sign is dealt with as a prinpfx4 and the portion after portion before the at-sign is dealt with as a prinpfx4 and the
is dealt with as a prinsfx4. portion after is dealt with as a prinsfx4.
12.4.2. Processing of Server Id Strings 12.4.2. Processing of Server Id Strings
Server id strings typically appear in responses (as attribute values) Server id strings typically appear in responses (as attribute values)
and only appear in requests as attribute value presented to VERIFY and only appear in requests as an attribute value presented to VERIFY
and NVERIFY. With that exception, they are not subject to server and NVERIFY. With that exception, they are not subject to server
validation and posible rejection. It is not expected that clients validation and posible rejection. It is not expected that clients
will typically do such validation on receipt of responses but they will typically do such validation on receipt of responses but they
may as a way to check for proper server behavior. The responsibility may as a way to check for proper server behavior. The responsibility
for sending correct UTF-8 strings is with the server. for sending correct UTF-8 strings is with the server.
Servers are identified by either server names of IP addresses. Once Servers are identified by either server names or IP addresses. Once
an id has been identified as an IP address, then there is no an id has been identified as an IP address, then there is no
processing specific to internationalization to be done, since such an processing specific to internationalization to be done, since such an
address must be ASCII to be valid. address must be ASCII to be valid.
Identifiers which are not valid IP addresses are treated as server
names for which see below. There are fifteen top-level domains that
consist of two characters, each within the range a-f. Given that, it
is possible to have a string such as bb.bb.bb.bb, which might be
either an IP address or a server name. It is recommended that in
such cases, a check for a valid server name be done first and the
string interpreted as an IP address only if it found that the string
is not a server name.
12.5. String Types without Internationalization Processing 12.5. String Types without Internationalization Processing
There are a number of types of strings which, for a number of There are a number of types of strings which, for a number of
different reasons, do not require any internationalization-specific different reasons, do not require any internationalization-specific
handling, such as valdiation of UTF-8, normaliztion, or character handling, such as validation of UTF-8, normalization, or character
mapping or checking. This does not necessarily mean that the strings mapping or checking. This does not necessarily mean that the strings
need not be UTF-8. In some case, other checking on the string need not be UTF-8. In some case, other checking on the string
ensures that they are valid UTF-8, without doing any checking ensures that they are valid UTF-8, without doing any checking
specific to internationalization. specific to internationalization.
The following are the specific types: The following are the specific types:
comptag4 strings are an aid to debugging and the sender should avoid comptag4 strings are an aid to debugging and the sender should avoid
confusion by not using anything but valid UTF-8. But any work confusion by not using anything but valid UTF-8. But any work
validating the string or modifying it would just add complication validating the string or modifying it would only add complication
to a mechanism whose basic function is best supported by making it to a mechanism whose basic function is best supported by making it
not subject to any checking and having data maximally available to not subject to any checking and having data maximally available to
be looked at in a network trace. be looked at in a network trace.
fattr4_mimetype strings need to be validated by matching against a fattr4_mimetype strings need to be validated by matching against a
list of valid mime types. Since these are all ASCII, no list of valid mime types. Since these are all ASCII, no
processing specific to internationaliztion is required since processing specific to internationaliztion is required since
anything that does not match is invalid and anything which does anything that does not match is invalid and anything which does
not obey the rules of UTF-8 will not be ASCII and consequently not obey the rules of UTF-8 will not be ASCII and consequently
will not match, and will be invalid. will not match, and will be invalid.
skipping to change at page 171, line 11 skipping to change at page 172, line 9
o Server names as they appear in the fs_locations attribute. Note o Server names as they appear in the fs_locations attribute. Note
that for most purposes, such server names will only be sent by the that for most purposes, such server names will only be sent by the
server to the client. The exception is use of the fs_locations server to the client. The exception is use of the fs_locations
attribute in a VERIFY or NVERIFY operation. attribute in a VERIFY or NVERIFY operation.
o Principal suffixes which are used to denote sets of users and o Principal suffixes which are used to denote sets of users and
groups, and are in the form of domain names. groups, and are in the form of domain names.
The general rules for handling all of these domain-related strings The general rules for handling all of these domain-related strings
are similar and independent of role of the sender or receiver as are similar and independent of role the of the sender or receiver as
client or sender, although the consequences of failure to obey these client or server although the consequences of failure to obey these
rules may be different for client or server. rules may be different for client or server. The server can report
errors when it is sent invalid strings, whereas the client will
simply ignore invalid string or use a default value in their place.
The string sent SHOULD be in the form of a U-label although it MAY be The string sent SHOULD be in the form of a U-label although it MAY be
in the form of an A-label or a UTF-8 string that would not map to in the form of an A-label or a UTF-8 string that would not map to
itself when canonicalized by applying ToUnicode(ToASCII(...)). The itself when canonicalized by applying ToUnicode(ToASCII(...)). The
receiver needs to be able to accept domain and server names in any of receiver needs to be able to accept domain and server names in any of
the formats allowed. The server MUST reject, using the the error the formats allowed. The server MUST reject, using the the error
NFS4ERR_INVAL, a string which is not valid UTF-8 or which begins with NFS4ERR_INVAL, a string which is not valid UTF-8 or which begins with
"xn--" and violates the rules for a valid A-label. "xn--" and violates the rules for a valid A-label.
When a domain string is part of id@domain or group@domain, the server When a domain string is part of id@domain or group@domain, the server
SHOULD map domain strings which are A-labels or are UTF-8 domain SHOULD map domain strings which are A-labels or are UTF-8 domain
names which are not U-labels, to the corresponding U-label, using names which are not U-labels, to the corresponding U-label, using
ToUnicode(domain) or ToUnicode(ToASCII(domain)). As a result, the ToUnicode(domain) or ToUnicode(ToASCII(domain)). As a result, the
domain name returned within a userid on a GETATTR may not match that domain name returned within a userid on a GETATTR may not match that
sent when the userid is set using SETATTR, although when this sent when the userid is set using SETATTR, although when this
happens, the domain will be in the form of a U-label. When the happens, the domain will be in the form of a U-label. When the
server does not map domain strings which are not U-labels into a server does not map domain strings which are not U-labels into a
U-label, which it MAY do, it MUST NOT modify the domain and the U-label, which it MAY do, it MUST NOT modify the domain and the
domain returned on a GETATTR of the userid MUST be the same as that domain returned on a GETATTR of the userid MUST be the same as that
using when setting the userid by the SETATTTR. used when setting the userid by the SETATTTR.
The server MAY implement VERIFY and NVERIFY without translating The server MAY implement VERIFY and NVERIFY without translating
internal state to a string form, so that, for example, a user internal state to a string form, so that, for example, a user
principal which represents a specific numeric user id, will match a principal which represents a specific numeric user id, will match a
different principal string which represents the same numeric user id. different principal string which represents the same numeric user id.
12.7. String Types with NFS-specific Processing 12.7. String Types with NFS-specific Processing
For a number of data types within NFSv4, the primary responsbibility For a number of data types within NFSv4, the primary responsbibility
for internationalization-related handling is that of some entity for internationalization-related handling is that of some entity
other than the server itself (see below for details). In these other than the server itself (see below for details). In these
situations, the primary responsibility of NFS version 4 is to provide situations, the primary responsibility of NFS version 4 is to provide
a framework in which that other entity (file system and server a framework in which that other entity (file system and server
operating system principal naming framework) to implement its own operating system principal naming framework) implements its own
decisions while establishing rules to limit interoperability issues. decisions while establishing rules to limit interoperability issues.
This pattern applies to the following data types: This pattern applies to the following data types:
o In the case of name components (strings of type component4), the o In the case of name components (strings of type component4), the
server-side file system implementation (of which there may be more server-side file system implementation (of which there may be more
than one for a particular server) deals with internationalization than one for a particular server) deals with internationalization
issues, in a fashion that is appropriate to NFS version 4, other issues, in a fashion that is appropriate to NFS version 4, other
remote file access protocols, and local file access methods. See remote file access protocols, and local file access methods. See
"Handling of File Came Components" for the detailed treatment. "Handling of File Name Components" for the detailed treatment.
o In the case of link text strings (strings of type lintext4), the o In the case of link text strings (strings of type lintext4), the
issues are similar, but file systems are restricted in the set of issues are similar, but file systems are restricted in the set of
acceptable internationalization-related processing that they may acceptable internationalization-related processing that they may
do, principally because symbolic links may contain name componetns do, principally because symbolic links may contain name componetns
that, when used, are presented to other file systems and/or other that, when used, are presented to other file systems and/or other
servers. See "Processing of Link Text" for the detailed servers. See "Processing of Link Text" for the detailed
treatment. treatment.
o In the case of principal prefix strings, any decisions regarding o In the case of principal prefix strings, any decisions regarding
internationalization are the responsibility of the server internationalization are the responsibility of the server
operating systems which may make its own rules regarding user and operating systems which may make its own rules regarding user and
group name encoding. See "Processing of Principal Prefixes" for group name encoding. See "Processing of Principal Prefixes" for
the detailed treatment. the detailed treatment.
12.7.1. Handling of File Came Components 12.7.1. Handling of File Name Components
There are a number of places within client and server where file name There are a number of places within client and server where file name
components are processed: components are processed:
o On the client, file names may be processed as part of forming NFS o On the client, file names may be processed as part of forming NFS
version 4 requests. Any such processing will reflect specific version 4 requests. Any such processing will reflect specific
needs of the client's environment and will be treated as out-of- needs of the client's environment and will be treated as out-of-
scope from the viewpoint of this specification. scope from the viewpoint of this specification.
o On the server, file names are processed as part of processing NFS o On the server, file names are processed as part of processing NFS
skipping to change at page 174, line 9 skipping to change at page 175, line 9
o One alternate character repertoire is to represent file name o One alternate character repertoire is to represent file name
components as strings of bytes with no protocol-defined encoding components as strings of bytes with no protocol-defined encoding
of multi-byte characters. Most typically, implementations that of multi-byte characters. Most typically, implementations that
support this single-byte alternative will make it available as an support this single-byte alternative will make it available as an
option set by an administrator for all file systems within a option set by an administrator for all file systems within a
server or for some particular file systems. If a server accepts server or for some particular file systems. If a server accepts
non-UTF-8 strings anywhere within a specific file system, then it non-UTF-8 strings anywhere within a specific file system, then it
MUST do so throughout the entire file system. MUST do so throughout the entire file system.
o Another alternate character repertoires is the set of codepoints, o Another alternate character repertoire is the set of codepoints,
representable by the file system, most typically UCS-4. representable by the file system, most typically UCS-4.
Individual file system implementations may have more restricted Individual file system implementations may have more restricted
character repertoires, as for example file system that only are character repertoires, as for example file system that only are
capable of storing names consisting of UCS-2 characters. When this capable of storing names consisting of UCS-2 characters. When this
is the case, and the character repertoire is not restricted to is the case, and the character repertoire is not restricted to
single-byte characters, characters not within that repertoire are single-byte characters, characters not within that repertoire are
treated as prohibited and the error NFS4ERR_BADCHAR is returned by treated as prohibited and the error NFS4ERR_BADCHAR is returned by
the server when that character is encountered. the server when that character is encountered.
Strings are intended to be in UTF-8 format and servers SHOULD return Strings are intended to be in UTF-8 format and servers SHOULD return
NFS4ERR_INVAL, as discussed above, when the characters sent are not NFS4ERR_INVAL, as discussed above, when the characters sent are not
valid UTF-8. When the character repertoire consists of single-byte valid UTF-8. When the character repertoire consists of single-byte
characters, UTF-8 is not enforced. Such situations should be characters, UTF-8 is not enforced. Such situations should be
restricted to those where use is within a restricted environment restricted to those where use is within a restricted environment
where a single character mapping locale can be administratively where a single character mapping locale can be administratively
enforced, allowing a file name to be treated as string of bytes, enforced, allowing a file name to be treated as a string of bytes,
rather than as a string of characters. Such an arrangement might be rather than as a string of characters. Such an arrangement might be
necessary when NFS version 4 access to a file system containing names necessary when NFS version 4 access to a file system containing names
which are not valid UTF-8 needs to be provided. which are not valid UTF-8 needs to be provided.
However, in any of the following situations, file names have to be However, in any of the following situations, file names have to be
treated as strings of characters and servers MUST return treated as strings of Unicode characters and servers MUST return
NFS4ERR_INVAL when file names that are not in UTF-8 format: NFS4ERR_INVAL when file names that are not in UTF-8 format:
o Case-insensitive comparisons are specified by the file system and o Case-insensitive comparisons are specified by the file system and
any characters sent contain non-ASCII byte codes. any characters sent contain non-ASCII byte codes.
o Any normalization constraints are enforced by the server or file o Any normalization constraints are enforced by the server or file
system implementation. system implementation.
o The server accepts a given name when creating a file and reports a o The server accepts a given name when creating a file and reports a
different one when the directory is being examined. different one when the directory is being examined.
skipping to change at page 175, line 11 skipping to change at page 176, line 11
non-UTF-8 string, if NFS4ERR_INVAL is not returned, then name non-UTF-8 string, if NFS4ERR_INVAL is not returned, then name
components will be treated as opaque and those sorts of modifications components will be treated as opaque and those sorts of modifications
will not be seen. will not be seen.
12.7.1.3. Case-based Mapping Used for Component4 Strings 12.7.1.3. Case-based Mapping Used for Component4 Strings
Case-based mapping is not always a required part of server processing Case-based mapping is not always a required part of server processing
of name components. However, if the NFS version 4 file server of name components. However, if the NFS version 4 file server
supports the case_insensitive file system attribute, and if the supports the case_insensitive file system attribute, and if the
case_insensitive attribute is true for a given file system, the NFS case_insensitive attribute is true for a given file system, the NFS
version 4 server must use the Unicode case mapping tables for the version 4 server MUST use the Unicode case mapping tables for the
version of Unicode corresponding to the character repertoire. In the version of Unicode corresponding to the character repertoire. In the
case where the character repertoire is UCS-2 or UCS-4, the case case where the character repertoire is UCS-2 or UCS-4, the case
mapping tables from the latest available version of Unicode should be mapping tables from the latest available version of Unicode SHOULD be
used. used.
If the case_preserving attribute is present and set to false, then If the case_preserving attribute is present and set to false, then
the NFS version 4 server MUST use the corresponding Unicode case the NFS version 4 server MUST use the corresponding Unicode case
mapping table to map case when processing component4 strings. mapping table to map case when processing component4 strings.
Whether the server maps from lower to upper case or the upper to Whether the server maps from lower to upper case or the upper to
lower case is a matter for implementation choice. lower case is a matter for implementation choice.
Stringprep Table B.2 should not be used for these purpose since it is Stringprep Table B.2 should not be used for these purpose since it is
limited to Unicode version 3.2 and also because it erroneously maps limited to Unicode version 3.2 and also because it erroneously maps
skipping to change at page 175, line 37 skipping to change at page 176, line 37
(SMALL LETTER SHARP S and CAPITAL LETTER SHARP S). (SMALL LETTER SHARP S and CAPITAL LETTER SHARP S).
Clients should be aware that servers may have mapped SMALL LETTER Clients should be aware that servers may have mapped SMALL LETTER
SHARP S to the string "ss" when case-insensitive mapping is in SHARP S to the string "ss" when case-insensitive mapping is in
effect, with result that file whose name contains SMALL LETTER SHARP effect, with result that file whose name contains SMALL LETTER SHARP
S may have that character replaced by "ss" or "SS". S may have that character replaced by "ss" or "SS".
12.7.1.4. Other Mapping Used for Component4 Strings 12.7.1.4. Other Mapping Used for Component4 Strings
Other than for issues of case mapping, an NFS version 4 server SHOULD Other than for issues of case mapping, an NFS version 4 server SHOULD
limit visible (i.e. those that change the name of file to reflect limit visible (i.e., those that change the name of file to reflect
those mappings to those from from a subset of the stringprep table those mappings to those from from a subset of the stringprep table
B.1. Note particularly, the mapings from U+200C and U+200D to the B.1. Note particularly, the mapings from U+200C and U+200D to the
empty string should be avoided, due to their undesirable effect on empty string should be avoided, due to their undesirable effect on
some strings in Farsi. some strings in Farsi.
Table B.1 may be used but it should be used only if required by the Table B.1 may be used but it should be used only if required by the
local file system implementation. For example, if the file system in local file system implementation. For example, if the file system in
question accepts file names containing the MONGOLIAN TODO SOFT HYPHEN question accepts file names containing the MONGOLIAN TODO SOFT HYPHEN
character (U+1806) and they are distinct from the corresponding file character (U+1806) and they are distinct from the corresponding file
names with this character removed, then using Table B.1 will cause names with this character removed, then using Table B.1 will cause
functional problems when clients attempt to interact with that file functional problems when clients attempt to interact with that file
system. The NFS version 4 server implementation including the system. The NFS version 4 server implementation including the
filesystem MUST NOT silently remove characters not within Table B.1. filesystem MUST NOT silently remove characters not within Table B.1.
If an implementation wishes to eliminate other characters because it If an implementation wishes to eliminate other characters because it
is believed that allowing component name versions that both include is believed that allowing component name versions that both include
the character and not have while otherwise the same, will contribute the character and do not have while otherwise the same, will
to confusion, it has two options: contribute to confusion, it has two options:
o Treat the characters as prohibited and return NFS4ERR_BADCHAR. o Treat the characters as prohibited and return NFS4ERR_BADCHAR.
o Eliminate the character as part of the name matching processing, o Eliminate the character as part of the name matching processing,
while retaining it when a file is created. This would be while retaining it when a file is created. This would be
analogous to file systems that are both case-insensitive and case- analogous to file systems that are both case-insensitive and case-
preserving,as dicussed above, or those which are both preserving,as dicussed above, or those which are both
normalization-insensitive and normalization-preserving, as normalization-insensitive and normalization-preserving, as
discussed below. The handling will be insensitive to presence of discussed below. The handling will be insensitive to the presence
the chosen characters while preserving the presence or absence of of the chosen characters while preserving the presence or absence
such chatacters within names. of such characters within names.
Note that the second of these choices is a desirable way to handle Note that the second of these choices is a desirable way to handle
characters within table B.1, again with the exception of U+200C and characters within table B.1, again with the exception of U+200C and
U+200D, which can cause issues for Farsi. U+200D, which can cause issues for Farsi.
In addition to modification due to normalization, discussed below, In addition to modification due to normalization, discussed below,
clients have to be able to deal with name modifications and other clients have to be able to deal with name modifications and other
consequences of character mapping on the server, as discussed above. consequences of character mapping on the server, as discussed above.
12.7.1.5. Normalization Issues for Component Strings 12.7.1.5. Normalization Issues for Component Strings
The issues are best discussed separately for the server and the The issues are best discussed separately for the server and the
client. It is important to note that the server and client may have client. It is important to note that the server and client may have
different approaches to this area, and that the server choice may not different approaches to this area, and that the server choice may not
match the client operating environment so the issue of mismatches and match the client operating environment. The issue of mismatches and
how they will be dealt with by the client is discussed in a later how they may be best dealt with by the client is discussed in a later
section. section.
12.7.1.5.1. Server Normalization Issues for Component Strings 12.7.1.5.1. Server Normalization Issues for Component Strings
The NFS version 4 does not specify required use of a particular The NFS version 4 does not specify required use of a particular
normalization form for component4 strings. Therefore, the server may normalization form for component4 strings. Therefore, the server may
receive unnormalized strings or strings that reflect either receive unnormalized strings or strings that reflect either
normalization form within protocol requests and responses. If the normalization form within protocol requests and responses. If the
operating environment requires normalization, then the server file system requires normalization, then the server implementation
implementation must normalize component4 strings within the protocol must normalize component4 strings within the protocol server before
server before presenting the information to the local file system. presenting the information to the local file system.
With regard to normalization, servers have the following choices, With regard to normalization, servers have the following choices,
with the possibility that different choices may be selected for with the possibility that different choices may be selected for
different file systems. different file systems.
o Implement a particular normalization form, either NFC, or NFD, in o Implement a particular normalization form, either NFC, or NFD, in
which case file names received from a client are converted to that which case file names received from a client are converted to that
normalization form and as a consequence, the client will always normalization form and as a consequence, the client will always
receive names in that normalization form. If this option is receive names in that normalization form. If this option is
chosen, then it is impossible to create two files in the same chosen, then it is impossible to create two files in the same
directory that have different names which map to the same name directory that have different names which map to the same name
when normalized. when normalized.
o Implement handling which is both normalization-insensitive and o Implement handling which is both normalization-insensitive and
normalization-preserving. This makes it impossible to create two normalization-preserving. This makes it impossible to create two
files in the same directory that have two different canonically files in the same directory that have two different canonically
equivalent name, i.e. names which map to the same name when equivalent names, i.e., names which map to the same name when
normalized. However, unlike the previous option, clients will not normalized. However, unlike the previous option, clients will not
have the names that they present modified to meet the server's have the names that they present modified to meet the server's
normalization constraints. normalization constraints.
o Implement normalization-sensitive handling without enforcing a o Implement normalization-sensitive handling without enforcing a
normalization form constraint on file names. This exposes the normalization form constraint on file names. This exposes the
client to the possibility that two files can be created in the client to the possibility that two files can be created in the
same directory which have different names which map to the same same directory which have different names which map to the same
name when normalized. This may be a significant issue when client name when normalized. This may be a significant issue when
which use different normalization forms are used on the same file clients which use different normalization forms are used on the
system, but this issue needs to be set against the difficulty of same file system, but this issue needs to be set against the
providing other sorts of normalization handling for some existing difficulty of providing other sorts of normalization handling for
file systems. some existing file systems.
12.7.1.5.2. Client Normalization Issues for Component Strings 12.7.1.5.2. Client Normalization Issues for Component Strings
The client, in processing name components, needs to deal with the The client, in processing name components, needs to deal with the
fact that the server may impose normalization on file name components fact that the server may impose normalization on file name components
presented to it. As a result, a file can be created within a presented to it. As a result, a file can be created within a
directory and that name may have different name due to normalization directory and that name be different from that sent by the client due
at the server. to normalization at the server.
Client operating environments differ in their handling of canonically Client operating environments differ in their handling of canonically
equivalent name. Some environments treat canonically equivalent equivalent names. Some environments treat canonically equivalent
strings as essentially equal and we will call these environments strings as essentially equal and we will call these environments
normalization-aware. Others, because of the pattern of their normalization-aware. Others, because of the pattern of their
development with regard to these issues treat different strings as development with regard to these issues treat different strings as
different, even if they are canonically equivalent. We call these different, even if they are canonically equivalent. We call these
normalization-unaware. normalization-unaware.
We discuss below issues that may arise when each of these types of
environments interact with the various types of file systems, with
regard to normalization handling. Note that complexity for the
client is increased given that there are no file system attributes to
determine the normalization handling present for that file system.
Where the client has the ability to create files (file system not
read-only and security allows it), attempting to create multiple
files with canonically equivalent names and looking at success
paaaters and the names assigned by the server to these files can
serve as a way to determine the relevant information.
Normalization-aware environments interoperate most normally with Normalization-aware environments interoperate most normally with
servers that either impose a given normalization form or those that servers that either impose a given normalization form or those that
implement name handling which is both normalization-insensitive and implement name handling which is both normalization-insensitive and
normalization-preserving name handling. However, clients need to be normalization-preserving name handling. However, clients need to be
prepared to interoperate with servers that have normalization- prepared to interoperate with servers that have normalization-
sensitive file naming. In this situation, the client needs to be sensitive file naming. In this situation, the client needs to be
prepared for the fact that a directory may contain multiple names prepared for the fact that a directory may contain multiple names
that it considers equivalent. that it considers equivalent.
The following suggestions may be helpful in handling interoperability
issues for normalization-aware client environments, when they
interact with normalization-sensitive file systems.
When READDIR is done, the names returned may include names that do
not match the client's normalization form, but instead are other
names canonically equivalent to the normalized name.
When it can be determined that a normalization-insensitive server
file system is not involved, the client can simply normalize
filename components strings to its preferred normalization form.
When it cannot be determined that a normalization-insensitive
server file system is not involved, the client is generally best
advised to process incoming name components so as to allow all
name components in a canonical equivalence class to be together.
When only a single member of class exists, it should generally
mapped directly to the preferred normalization form, whether the
name was of that form or not.
When the client sees multiple names that are canonically
equivalent, it is clear you have a file systen which is
normalization sensitive. Clients should generally replace each
canonically equivalent name with one that appends some
distinguishing suffix, usually including a number. The numbers
should be assigned so that each distinct possible name with the
set of canonically equivalent names has an assigned numeric value.
Note that for some cases in which there are multiple instances of
strings that might be composed or decomposed and/or situations
with multiple diacritics to be applied to the same character, the
class might be large.
When interacting with a normalization-sensitive filesystem, it may
be that the environment contains clients or implementations local
to the OS in which the file system is embedded, which use a
different normalization form. In such situations, a LOOKUP may
well fail, even though the directory contains a name canonically
equivalent to the name sought. One solution to this problem is to
re-do the LOOKUP in that situation with name converted to the
alternate normalization form.
In the case in which normalization-unaware clients are involved in
the mix, LOOKUP can fail and then the second lOOKUP, described
above can also fail, even though there may well be a oanonically
equivalent name in the directory. One possible approach in that
case is to use a READDIR to find the equivalent name and lookup
that, although this can greatly add to client implementation
complexity.
When interacting with a normalization-sensitive filesystem, the
situation where the environment contains clients or
implementations local to the OS in which the file system is
embedded, which use a different normalization form can also cause
issues when a file (or symlink or directory, etc.) is being
created. In such cases, you may be able to create an object of
the specified name even though, the directory contains a
canonically equivalent name. Similar issues can occur with LINK
and RENAME. The client can't really do much about such
sitautions, except be aware that they may occur. That's one of
the reasons normalization-sensitive server file system
implementations can be problematic to use when
internationalization issues are important.
Normalization-unaware environments interoperate most normally with Normalization-unaware environments interoperate most normally with
servers that implement normalization-sensitive file naming. However, servers that implement normalization-sensitive file naming. However,
clients need to be prepared to interoperate with servers that impose clients need to be prepared to interoperate with servers that impose
a given normalization form or that implement name handling which is a given normalization form or that implement name handling which is
both normalization-insensitive and normalization-preserving. In the both normalization-insensitive and normalization-preserving. In the
former case, a file created with a given name may find it changed to former case, a file created with a given name may find it changed to
a different (although related name). In both cases, the client will a different (although related name). In both cases, the client will
have to deal with the fact that it is unable to create two names have to deal with the fact that it is unable to create two names
within a directory that are canonically equivalent. within a directory that are canonically equivalent.
Note that although the client implementation itself and the kernel
implementation may be normalization-unware, treating name components
as strings not subject to normalization, the environment as a whole
may be normalization-aware if commonly used libraries result in an
application environment where a single normalization form is used
throughout. Because of this, normalization-unaware environments may
be relatively rare.
The following suggestions may be helpful in handling interoperability
issues for truely normalization-unaware client environments, when
they interact with file systems other than those which are
normalization-sensitive. The issues tend to be the inverse of those
for normalization-aware environments. The implementer should be
careful not to erroneously treat the environment as normalization-
unaware, based solely on the details of the kernel implementation.
Unless the file system is normalization-preserving, when files (or
other objects) are created, the object name as reported by a
READDIR of the associated directory may show a name different than
the one used to create the object. This behavior is something
that the client has to accept. Since it has no preferred
normalization form, it has no way of converting the name to a
preferred form.
In situations where there is an attempt to create multiple objects
in the same directory which have canonically-equivalent names.
these file systems will either report that an object of name
already exists or simply open a file of that other name.
If it desired to have those two obects in the same directory, the
names must be made not canonically equivalent. It is possible to
append some distinguishing character to the name of the second
object but in clients having a typical file API (such as POSIX),
the fact that the name change occurred cannot be propagated back
to the requester.
In cases where a client is application-specific, it may be
possible for it to deal with such a collision by modifying the
name and taking note of the changed name.
12.7.1.6. Prohibited Characters for Component Names 12.7.1.6. Prohibited Characters for Component Names
The NFS version 4 protocol does not specify particular characters The NFS version 4 protocol does not specify particular characters
that may not appear in component names. File systems may have their that may not appear in component names. File systems may have their
own set of prohibited characters for which the error NFS4ERR_BADCHAR own set of prohibited characters for which the error NFS4ERR_BADCHAR
should be returned by the server. Clients need to be prepared for should be returned by the server. Clients need to be prepared for
this error to occur whenever file name components are presented to this error to occur whenever file name components are presented to
the server. the server.
Clients whose character repertoire for acceptable characters in file Clients whose character repertoire for acceptable characters in file
skipping to change at page 179, line 13 skipping to change at page 182, line 32
returning NFS4ERR_BADNAME. returning NFS4ERR_BADNAME.
Clients may encounter names with bidirectional strings returned in Clients may encounter names with bidirectional strings returned in
responses from the server. If clients treat such strings as not responses from the server. If clients treat such strings as not
valid file name components, it is up to the client whether it simply valid file name components, it is up to the client whether it simply
ignores these files or modifies the name component to meet its own ignores these files or modifies the name component to meet its own
rules for acceptable name component strings. rules for acceptable name component strings.
12.7.2. Processing of Link Text 12.7.2. Processing of Link Text
Symbolic link text is defined as utf8_should and therefore the server Symbolic link text is defined as utf8val_should and therefore the
SHOULD validate link text on a CREATE and return NFS4ERR_INVAL if it server SHOULD validate link text on a CREATE and return NFS4ERR_INVAL
is is not valid UTF-8. Note that file systems which treat names as if it is is not valid UTF-8. Note that file systems which treat
strings of byte are an exception for which such validation need not names as strings of byte are an exception for which such validation
be done. One other situation in which an NFS version 4 might choose need not be done. One other situation in which an NFS version 4
(or be configured) not to make such a check is when links within file might choose (or be configured) not to make such a check is when
system reference names in another which is configured to treat names links within file system reference names in another which is
as strings of bytes. configured to treat names as strings of bytes.
On the other hand, UTF-8 validation of symbolic link text need not be On the other hand, UTF-8 validation of symbolic link text need not be
done on the data resulting from a READLINK. Such data might have done on the data resulting from a READLINK. Such data might have
been stored by an NFS Version 4 server configured to allow non-UTF-8 been stored by an NFS Version 4 server configured to allow non-UTF-8
link text or it might have resulted from symbolic link text stored link text or it might have resulted from symbolic link text stored
via local file system access or access via another remote file access via local file system access or access via another remote file access
protocol. protocol.
Note that because of the role of the symbolic link, as data stored Note that because of the role of the symbolic link, as data stored
and read by the user, other sorts of validations or modifications and read by the user, other sorts of validations or modifications
skipping to change at page 185, line 9 skipping to change at page 188, line 19
present at the server. It may have been relocated, migrated to present at the server. It may have been relocated, migrated to
another server or may have never been present. The client may obtain another server or may have never been present. The client may obtain
the new file system location by obtaining the "fs_locations" or the new file system location by obtaining the "fs_locations" or
attribute for the current filehandle. For further discussion, refer attribute for the current filehandle. For further discussion, refer
to Section 7 to Section 7
13.1.2.5. NFS4ERR_NOFILEHANDLE (Error Code 10020) 13.1.2.5. NFS4ERR_NOFILEHANDLE (Error Code 10020)
The logical current or saved filehandle value is required by the The logical current or saved filehandle value is required by the
current operation and is not set. This may be a result of a current operation and is not set. This may be a result of a
malformed COMPOUND operation (i.e. no PUTFH or PUTROOTFH before an malformed COMPOUND operation (i.e., no PUTFH or PUTROOTFH before an
operation that requires the current filehandle be set). operation that requires the current filehandle be set).
13.1.2.6. NFS4ERR_NOTDIR (Error Code 20) 13.1.2.6. NFS4ERR_NOTDIR (Error Code 20)
The current (or saved) filehandle designates an object which is not a The current (or saved) filehandle designates an object which is not a
directory for an operation in which a directory is required. directory for an operation in which a directory is required.
13.1.2.7. NFS4ERR_STALE (Error Code 70) 13.1.2.7. NFS4ERR_STALE (Error Code 70)
The current or saved filehandle value designating an argument to the The current or saved filehandle value designating an argument to the
skipping to change at page 191, line 31 skipping to change at page 194, line 38
currently held lock for the current lock owner and does not precisely currently held lock for the current lock owner and does not precisely
match a single such lock where the server does not support this type match a single such lock where the server does not support this type
of request, and thus does not implement POSIX locking semantics. See of request, and thus does not implement POSIX locking semantics. See
Section 15.12.5, Section 15.13.5, and Section 15.14.5 for a Section 15.12.5, Section 15.13.5, and Section 15.14.5 for a
discussion of how this applies to LOCK, LOCKT, and LOCKU discussion of how this applies to LOCK, LOCKT, and LOCKU
respectively. respectively.
13.1.8.9. NFS4ERR_OPENMODE (Error Code 10038) 13.1.8.9. NFS4ERR_OPENMODE (Error Code 10038)
The client attempted a READ, WRITE, LOCK or other operation not The client attempted a READ, WRITE, LOCK or other operation not
sanctioned by the stateid passed (e.g. writing to a file opened only sanctioned by the stateid passed (e.g., writing to a file opened only
for read). for read).
13.1.9. Reclaim Errors 13.1.9. Reclaim Errors
These errors relate to the process of reclaiming locks after a server These errors relate to the process of reclaiming locks after a server
restart. restart.
13.1.9.1. NFS4ERR_GRACE (Error Code 10013) 13.1.9.1. NFS4ERR_GRACE (Error Code 10013)
The server is in its recovery or grace period which should at least The server is in its recovery or grace period which should at least
skipping to change at page 197, line 8 skipping to change at page 200, line 36
| | NFS4ERR_DQUOT, NFS4ERR_FHEXPIRED, | | | NFS4ERR_DQUOT, NFS4ERR_FHEXPIRED, |
| | NFS4ERR_IO, NFS4ERR_MOVED, NFS4ERR_NOENT, | | | NFS4ERR_IO, NFS4ERR_MOVED, NFS4ERR_NOENT, |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, |
| | NFS4ERR_NOTSUPP, NFS4ERR_RESOURCE, | | | NFS4ERR_NOTSUPP, NFS4ERR_RESOURCE, |
| | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, |
| | NFS4ERR_STALE | | | NFS4ERR_STALE |
| OPEN_CONFIRM | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADHANDLE, | | OPEN_CONFIRM | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADHANDLE, |
| | NFS4ERR_BAD_SEQID, NFS4ERR_BAD_STATEID, | | | NFS4ERR_BAD_SEQID, NFS4ERR_BAD_STATEID, |
| | NFS4ERR_BADXDR, NFS4ERR_EXPIRED, | | | NFS4ERR_BADXDR, NFS4ERR_EXPIRED, |
| | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, | | | NFS4ERR_FHEXPIRED, NFS4ERR_INVAL, |
| | NFS4ERR_ISDIR, NFS4ERR_MOVED, | | | NFS4ERR_ISDIR, NFS4ERR_LEASE_MOVED, |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_OLD_STATEID, | | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, |
| | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | | | NFS4ERR_OLD_STATEID, NFS4ERR_RESOURCE, |
| | NFS4ERR_STALE, NFS4ERR_STALE_STATEID | | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, |
| | NFS4ERR_STALE_STATEID |
| OPEN_DOWNGRADE | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADHANDLE, | | OPEN_DOWNGRADE | NFS4ERR_ADMIN_REVOKED, NFS4ERR_BADHANDLE, |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_SEQID, | | | NFS4ERR_BADXDR, NFS4ERR_BAD_SEQID, |
| | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, | | | NFS4ERR_BAD_STATEID, NFS4ERR_DELAY, |
| | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, | | | NFS4ERR_EXPIRED, NFS4ERR_FHEXPIRED, |
| | NFS4ERR_INVAL, NFS4ERR_MOVED, | | | NFS4ERR_INVAL, NFS4ERR_LEASE_MOVED, |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_OLD_STATEID, | | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, |
| | NFS4ERR_RESOURCE, NFS4ERR_ROFS, | | | NFS4ERR_OLD_STATEID, NFS4ERR_RESOURCE, |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, | | | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, |
| | NFS4ERR_STALE_STATEID | | | NFS4ERR_STALE, NFS4ERR_STALE_STATEID |
| PUTFH | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | | PUTFH | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, |
| | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, | | | NFS4ERR_DELAY, NFS4ERR_FHEXPIRED, |
| | NFS4ERR_MOVED, NFS4ERR_SERVERFAULT, | | | NFS4ERR_MOVED, NFS4ERR_SERVERFAULT, |
| | NFS4ERR_STALE, NFS4ERR_WRONGSEC | | | NFS4ERR_STALE, NFS4ERR_WRONGSEC |
| PUTPUBFH | NFS4ERR_DELAY, NFS4ERR_SERVERFAULT, | | PUTPUBFH | NFS4ERR_DELAY, NFS4ERR_SERVERFAULT, |
| | NFS4ERR_WRONGSEC | | | NFS4ERR_WRONGSEC |
| PUTROOTFH | NFS4ERR_DELAY, NFS4ERR_SERVERFAULT, | | PUTROOTFH | NFS4ERR_DELAY, NFS4ERR_SERVERFAULT, |
| | NFS4ERR_WRONGSEC | | | NFS4ERR_WRONGSEC |
| READ | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | | READ | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, |
| | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, | | | NFS4ERR_BADHANDLE, NFS4ERR_BADXDR, |
skipping to change at page 199, line 20 skipping to change at page 203, line 12
| | NFS4ERR_NOTDIR, NFS4ERR_RESOURCE, | | | NFS4ERR_NOTDIR, NFS4ERR_RESOURCE, |
| | NFS4ERR_SERVERFAULT, NFS4ERR_STALE | | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE |
| SETATTR | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | | SETATTR | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, |
| | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADCHAR, | | | NFS4ERR_ATTRNOTSUPP, NFS4ERR_BADCHAR, |
| | NFS4ERR_BADHANDLE, NFS4ERR_BADOWNER, | | | NFS4ERR_BADHANDLE, NFS4ERR_BADOWNER, |
| | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, | | | NFS4ERR_BADXDR, NFS4ERR_BAD_STATEID, |
| | NFS4ERR_DELAY, NFS4ERR_DQUOT, | | | NFS4ERR_DELAY, NFS4ERR_DQUOT, |
| | NFS4ERR_EXPIRED, NFS4ERR_FBIG, | | | NFS4ERR_EXPIRED, NFS4ERR_FBIG, |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR, | | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_ISDIR, |
| | NFS4ERR_LOCKED, NFS4ERR_MOVED, | | | NFS4ERR_LEASE_MOVED, NFS4ERR_LOCKED, |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOSPC, | | | NFS4ERR_MOVED, NFS4ERR_NOFILEHANDLE, |
| | NFS4ERR_OLD_STATEID, NFS4ERR_OPENMODE, | | | NFS4ERR_NOSPC, NFS4ERR_OLD_STATEID, |
| | NFS4ERR_PERM, NFS4ERR_RESOURCE, | | | NFS4ERR_OPENMODE, NFS4ERR_PERM, |
| | NFS4ERR_ROFS, NFS4ERR_SERVERFAULT, | | | NFS4ERR_RESOURCE, NFS4ERR_ROFS, |
| | NFS4ERR_STALE, NFS4ERR_STALE_STATEID | | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE, |
| | NFS4ERR_STALE_STATEID |
| SETCLIENTID | NFS4ERR_BADXDR, NFS4ERR_CLID_INUSE, | | SETCLIENTID | NFS4ERR_BADXDR, NFS4ERR_CLID_INUSE, |
| | NFS4ERR_INVAL, NFS4ERR_RESOURCE, | | | NFS4ERR_DELAY, NFS4ERR_INVAL, |
| | NFS4ERR_SERVERFAULT | | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT |
| SETCLIENTID_CONFIRM | NFS4ERR_BADXDR, NFS4ERR_CLID_INUSE, | | SETCLIENTID_CONFIRM | NFS4ERR_BADXDR, NFS4ERR_CLID_INUSE, |
| | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | | | NFS4ERR_DELAY, NFS4ERR_RESOURCE, |
| | NFS4ERR_STALE_CLIENTID | | | NFS4ERR_SERVERFAULT, NFS4ERR_STALE_CLIENTID |
| VERIFY | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, | | VERIFY | NFS4ERR_ACCESS, NFS4ERR_ATTRNOTSUPP, |
| | NFS4ERR_BADCHAR, NFS4ERR_BADHANDLE, | | | NFS4ERR_BADCHAR, NFS4ERR_BADHANDLE, |
| | NFS4ERR_BADXDR, NFS4ERR_DELAY, | | | NFS4ERR_BADXDR, NFS4ERR_DELAY, |
| | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, | | | NFS4ERR_FHEXPIRED, NFS4ERR_GRACE, |
| | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, | | | NFS4ERR_INVAL, NFS4ERR_IO, NFS4ERR_MOVED, |
| | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOT_SAME, | | | NFS4ERR_NOFILEHANDLE, NFS4ERR_NOT_SAME, |
| | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, | | | NFS4ERR_RESOURCE, NFS4ERR_SERVERFAULT, |
| | NFS4ERR_STALE | | | NFS4ERR_STALE |
| WRITE | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, | | WRITE | NFS4ERR_ACCESS, NFS4ERR_ADMIN_REVOKED, |
| | NFS4ERR_BADXDR, NFS4ERR_BADHANDLE, | | | NFS4ERR_BADXDR, NFS4ERR_BADHANDLE, |
skipping to change at page 202, line 10 skipping to change at page 205, line 42
| | OPEN_DOWNGRADE, READ, SETATTR, WRITE | | | OPEN_DOWNGRADE, READ, SETATTR, WRITE |
| NFS4ERR_CB_PATH_DOWN | RENEW | | NFS4ERR_CB_PATH_DOWN | RENEW |
| NFS4ERR_CLID_INUSE | SETCLIENTID, SETCLIENTID_CONFIRM | | NFS4ERR_CLID_INUSE | SETCLIENTID, SETCLIENTID_CONFIRM |
| NFS4ERR_DEADLOCK | LOCK | | NFS4ERR_DEADLOCK | LOCK |
| NFS4ERR_DELAY | ACCESS, CB_GETATTR, CB_RECALL, CLOSE, | | NFS4ERR_DELAY | ACCESS, CB_GETATTR, CB_RECALL, CLOSE, |
| | CREATE, GETATTR, LINK, LOCK, LOCKT, | | | CREATE, GETATTR, LINK, LOCK, LOCKT, |
| | LOOKUPP, NVERIFY, OPEN, OPENATTR, | | | LOOKUPP, NVERIFY, OPEN, OPENATTR, |
| | OPEN_DOWNGRADE, PUTFH, PUTPUBFH, | | | OPEN_DOWNGRADE, PUTFH, PUTPUBFH, |
| | PUTROOTFH, READ, READDIR, READLINK, | | | PUTROOTFH, READ, READDIR, READLINK, |
| | REMOVE, RENAME, SECINFO, SETATTR, | | | REMOVE, RENAME, SECINFO, SETATTR, |
| | SETCLIENTID, SETCLIENTID_CONFIRM, |
| | VERIFY, WRITE | | | VERIFY, WRITE |
| NFS4ERR_DENIED | LOCK, LOCKT | | NFS4ERR_DENIED | LOCK, LOCKT |
| NFS4ERR_DQUOT | CREATE, LINK, OPEN, OPENATTR, RENAME, | | NFS4ERR_DQUOT | CREATE, LINK, OPEN, OPENATTR, RENAME, |
| | SETATTR, WRITE | | | SETATTR, WRITE |
| NFS4ERR_EXIST | CREATE, LINK, OPEN, RENAME | | NFS4ERR_EXIST | CREATE, LINK, OPEN, RENAME |
| NFS4ERR_EXPIRED | CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, | | NFS4ERR_EXPIRED | CLOSE, DELEGRETURN, LOCK, LOCKU, OPEN, |
| | OPEN_CONFIRM, OPEN_DOWNGRADE, READ, | | | OPEN_CONFIRM, OPEN_DOWNGRADE, READ, |
| | RELEASE_LOCKOWNER, RENEW, SETATTR, | | | RELEASE_LOCKOWNER, RENEW, SETATTR, |
| | WRITE | | | WRITE |
| NFS4ERR_FBIG | OPEN, SETATTR, WRITE | | NFS4ERR_FBIG | OPEN, SETATTR, WRITE |
skipping to change at page 202, line 47 skipping to change at page 206, line 32
| | RENAME, SECINFO, SETATTR, SETCLIENTID, | | | RENAME, SECINFO, SETATTR, SETCLIENTID, |
| | VERIFY, WRITE | | | VERIFY, WRITE |
| NFS4ERR_IO | ACCESS, COMMIT, CREATE, GETATTR, LINK, | | NFS4ERR_IO | ACCESS, COMMIT, CREATE, GETATTR, LINK, |
| | LOOKUP, LOOKUPP, NVERIFY, OPEN, | | | LOOKUP, LOOKUPP, NVERIFY, OPEN, |
| | OPENATTR, READ, READDIR, READLINK, | | | OPENATTR, READ, READDIR, READLINK, |
| | REMOVE, RENAME, SETATTR, VERIFY, WRITE | | | REMOVE, RENAME, SETATTR, VERIFY, WRITE |
| NFS4ERR_ISDIR | CLOSE, COMMIT, LINK, LOCK, LOCKT, | | NFS4ERR_ISDIR | CLOSE, COMMIT, LINK, LOCK, LOCKT, |
| | LOCKU, OPEN, OPEN_CONFIRM, READ, | | | LOCKU, OPEN, OPEN_CONFIRM, READ, |
| | READLINK, SETATTR, WRITE | | | READLINK, SETATTR, WRITE |
| NFS4ERR_LEASE_MOVED | CLOSE, DELEGPURGE, DELEGRETURN, LOCK, | | NFS4ERR_LEASE_MOVED | CLOSE, DELEGPURGE, DELEGRETURN, LOCK, |
| | LOCKT, LOCKU, READ, RELEASE_LOCKOWNER, | | | LOCKT, LOCKU, OPEN_CONFIRM, |
| | RENEW, WRITE | | | OPEN_DOWNGRADE, READ, |
| | RELEASE_LOCKOWNER, RENEW, SETATTR, |
| | WRITE |
| NFS4ERR_LOCKED | READ, SETATTR, WRITE | | NFS4ERR_LOCKED | READ, SETATTR, WRITE |
| NFS4ERR_LOCKS_HELD | CLOSE, RELEASE_LOCKOWNER | | NFS4ERR_LOCKS_HELD | CLOSE, RELEASE_LOCKOWNER |
| NFS4ERR_LOCK_NOTSUPP | LOCK | | NFS4ERR_LOCK_NOTSUPP | LOCK |
| NFS4ERR_LOCK_RANGE | LOCK, LOCKT, LOCKU | | NFS4ERR_LOCK_RANGE | LOCK, LOCKT, LOCKU |
| NFS4ERR_MLINK | LINK | | NFS4ERR_MLINK | LINK |
| NFS4ERR_MOVED | ACCESS, CLOSE, COMMIT, CREATE, | | NFS4ERR_MOVED | ACCESS, CLOSE, COMMIT, CREATE, |
| | DELEGRETURN, GETATTR, GETFH, LINK, | | | DELEGRETURN, GETATTR, GETFH, LINK, |
| | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, | | | LOCK, LOCKT, LOCKU, LOOKUP, LOOKUPP, |
| | NVERIFY, OPEN, OPENATTR, OPEN_CONFIRM, | | | NVERIFY, OPEN, OPENATTR, OPEN_CONFIRM, |
| | OPEN_DOWNGRADE, PUTFH, READ, READDIR, | | | OPEN_DOWNGRADE, PUTFH, READ, READDIR, |
skipping to change at page 235, line 30 skipping to change at page 238, line 30
(cfh), stateid, cinfo, rflags, open_confirm, attrset delegation (cfh), stateid, cinfo, rflags, open_confirm, 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
}; };
union createhow4 switch (createmode4 mode) { union createhow4 switch (createmode4 mode) {
case UNCHECKED4: case UNCHECKED4:
case GUARDED4: case GUARDED4:
fattr4 createattrs; fattr4 createattrs;
case EXCLUSIVE4: case EXCLUSIVE4:
verifier4 createverf; verifier4 createverf;
}; };
skipping to change at page 236, line 35 skipping to change at page 239, line 35
enum open_delegation_type4 { enum open_delegation_type4 {
OPEN_DELEGATE_NONE = 0, OPEN_DELEGATE_NONE = 0,
OPEN_DELEGATE_READ = 1, OPEN_DELEGATE_READ = 1,
OPEN_DELEGATE_WRITE = 2 OPEN_DELEGATE_WRITE = 2
}; };
enum open_claim_type4 { enum open_claim_type4 {
CLAIM_NULL = 0, CLAIM_NULL = 0,
CLAIM_PREVIOUS = 1, CLAIM_PREVIOUS = 1,
CLAIM_DELEGATE_CUR = 2, CLAIM_DELEGATE_CUR = 2,
CLAIM_DELEGATE_PREV = 3, CLAIM_DELEGATE_PREV = 3
}; };
struct open_claim_delegate_cur4 { struct open_claim_delegate_cur4 {
stateid4 delegate_stateid; stateid4 delegate_stateid;
component4 file; component4 file;
}; };
union open_claim4 switch (open_claim_type4 claim) { union open_claim4 switch (open_claim_type4 claim) {
/* /*
* No special rights to file. * No special rights to file.
skipping to change at page 252, line 47 skipping to change at page 255, line 47
is returned with a data length set to 0 (zero) and eof is set to is returned with a data length set to 0 (zero) and eof is set to
TRUE. The READ is subject to access permissions checking. TRUE. The READ is subject to access permissions checking.
If the client specifies a count value of 0 (zero), the READ succeeds If the client specifies a count value of 0 (zero), the READ succeeds
and returns 0 (zero) bytes of data again subject to access and returns 0 (zero) bytes of data again subject to access
permissions checking. The server may choose to return fewer bytes permissions checking. The server may choose to return fewer bytes
than specified by the client. The client needs to check for this than specified by the client. The client needs to check for this
condition and handle the condition appropriately. condition and handle the condition appropriately.
The stateid value for a READ request represents a value returned from The stateid value for a READ request represents a value returned from
a previous record lock or share reservation request. The stateid is a previous record lock or share reservation request or the stateid
used by the server to verify that the associated share reservation associated with a delegation. The stateid is used by the server to
and any record locks are still valid and to update lease timeouts for verify that the associated share reservation and any record locks are
the client. still valid and to update lease timeouts for the client.
If the read ended at the end-of-file (formally, in a correctly formed If the read ended at the end-of-file (formally, in a correctly formed
READ request, if offset + count is equal to the size of the file), or READ request, if offset + count is equal to the size of the file), or
the read request extends beyond the size of the file (if offset + the read request extends beyond the size of the file (if offset +
count is greater than the size of the file), eof is returned as TRUE; count is greater than the size of the file), eof is returned as TRUE;
otherwise it is FALSE. A successful READ of an empty file will otherwise it is FALSE. A successful READ of an empty file will
always return eof as TRUE. always return eof as TRUE.
If the current filehandle is not a regular file, an error will be If the current filehandle is not a regular file, an error will be
returned to the client. In the case the current filehandle returned to the client. In the case the current filehandle
skipping to change at page 256, line 22 skipping to change at page 259, line 22
For some filesystem environments, the directory entries "." and ".." For some filesystem environments, the directory entries "." and ".."
have special meaning and in other environments, they may not. If the have special meaning and in other environments, they may not. If the
server supports these special entries within a directory, they should server supports these special entries within a directory, they should
not be returned to the client as part of the READDIR response. To not be returned to the client as part of the READDIR response. To
enable some client environments, the cookie values of 0, 1, and 2 are enable some client environments, the cookie values of 0, 1, and 2 are
to be considered reserved. Note that the UNIX client will use these to be considered reserved. Note that the UNIX client will use these
values when combining the server's response and local representations values when combining the server's response and local representations
to enable a fully formed UNIX directory presentation to the to enable a fully formed UNIX directory presentation to the
application. application.
For READDIR arguments, cookie values of 1 and 2 should not be used For READDIR arguments, cookie values of 1 and 2 SHOULD NOT be used
and for READDIR results cookie values of 0, 1, and 2 should not be and for READDIR results cookie values of 0, 1, and 2 MUST NOT be
returned. returned.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
15.26.5. IMPLEMENTATION 15.26.5. IMPLEMENTATION
The server's filesystem directory representations can differ greatly. The server's filesystem directory representations can differ greatly.
A client's programming interfaces may also be bound to the local A client's programming interfaces may also be bound to the local
operating environment in a way that does not translate well into the operating environment in a way that does not translate well into the
NFS protocol. Therefore the use of the dircount and maxcount fields NFS protocol. Therefore the use of the dircount and maxcount fields
skipping to change at page 262, line 44 skipping to change at page 265, line 44
When the client holds delegations, it needs to use RENEW to detect When the client holds delegations, it needs to use RENEW to detect
when the server has determined that the callback path is down. When when the server has determined that the callback path is down. When
the server has made such a determination, only the RENEW operation the server has made such a determination, only the RENEW operation
will renew the lease on delegations. If the server determines the will renew the lease on delegations. If the server determines the
callback path is down, it returns NFS4ERR_CB_PATH_DOWN. Even though callback path is down, it returns NFS4ERR_CB_PATH_DOWN. Even though
it returns NFS4ERR_CB_PATH_DOWN, the server MUST renew the lease on it returns NFS4ERR_CB_PATH_DOWN, the server MUST renew the lease on
the record locks and share reservations that the client has the record locks and share reservations that the client has
established on the server. If for some reason the lock and share established on the server. If for some reason the lock and share
reservation lease cannot be renewed, then the server MUST return an reservation lease cannot be renewed, then the server MUST return an
error other than NFS4ERR_CB_PATH_DOWN, even if the callback path is error other than NFS4ERR_CB_PATH_DOWN, even if the callback path is
also down. also down. In the event that the server has conditions such that is
could return either NFS4ERR_CB_PATH_DOWN or NFS4ERR_LEASE_MOVED,
NFS4ERR_LEASE_MOVED MUST be handled first.
The client that issues RENEW MUST choose the principal, RPC security The client that issues RENEW MUST choose the principal, RPC security
flavor, and if applicable, GSS-API mechanism and service via one of flavor, and if applicable, GSS-API mechanism and service via one of
the following algorithms: the following algorithms:
o The client uses the same principal, RPC security flavor -- and if o The client uses the same principal, RPC security flavor -- and if
the flavor was RPCSEC_GSS -- the same mechanism and service that the flavor was RPCSEC_GSS -- the same mechanism and service that
was used when the client id was established via was used when the client id was established via
SETCLIENTID_CONFIRM. SETCLIENTID_CONFIRM.
skipping to change at page 280, line 6 skipping to change at page 283, line 6
stable is UNSTABLE4, the server is free to commit any part of the stable is UNSTABLE4, the server is free to commit any part of the
data and the metadata to stable storage, including all or none, data and the metadata to stable storage, including all or none,
before returning a reply to the client. There is no guarantee before returning a reply to the client. There is no guarantee
whether or when any uncommitted data will subsequently be committed whether or when any uncommitted data will subsequently be committed
to stable storage. The only guarantees made by the server are that to stable storage. The only guarantees made by the server are that
it will not destroy any data without changing the value of verf and it will not destroy any data without changing the value of verf and
that it will not commit the data and metadata at a level less than that it will not commit the data and metadata at a level less than
that requested by the client. that requested by the client.
The stateid value for a WRITE request represents a value returned The stateid value for a WRITE request represents a value returned
from a previous record lock or share reservation request. The from a previous record lock or share reservation request or the
stateid is used by the server to verify that the associated share stateid associated with a delegation. The stateid is used by the
reservation and any record locks are still valid and to update lease server to verify that the associated share reservation and any record
timeouts for the client. locks are still valid and to update lease timeouts for the client.
Upon successful completion, the following results are returned. The Upon successful completion, the following results are returned. The
count result is the number of bytes of data written to the file. The count result is the number of bytes of data written to the file. The
server may write fewer bytes than requested. If so, the actual server may write fewer bytes than requested. If so, the actual
number of bytes written starting at location, offset, is returned. number of bytes written starting at location, offset, is returned.
The server also returns an indication of the level of commitment of The server also returns an indication of the level of commitment of
the data and metadata via committed. If the server committed all the data and metadata via committed. If the server committed all
data and metadata to stable storage, committed should be set to data and metadata to stable storage, committed should be set to
FILE_SYNC4. If the level of commitment was at least as strong as FILE_SYNC4. If the level of commitment was at least as strong as
skipping to change at page 295, line 6 skipping to change at page 298, line 6
NFS Server", USENIX Conference Proceedings , June 1990. NFS Server", USENIX Conference Proceedings , June 1990.
[31] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997. [31] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997.
[32] Chiu, A., Eisler, M., and B. Callaghan, "Security Negotiation [32] 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 [33] 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.
[34] Noveck, D. and R. Burnett, "Implementation Guide for Referrals
in NFSv4", draft-ietf-nfsv4-referrals-00 (work in progress),
July 2005.
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 and Trond Myklebust read many David Black, Nico Williams, Mike Eisler, Trond Myklebust, and James
drafts of Section 12 and contributed numerous useful suggestions, Lentini read many drafts of Section 12 and contributed numerous
without which the necessary revision of that section for this useful suggestions, without which the necessary revision of that
document would not have been possible. section for this document would not have been possible.
Peter Staubach read almost all of the drafts of Section 12 leading to Peter Staubach read almost all of the drafts of Section 12 leading to
the published result and his numerous comments were always useful and the published result and his numerous comments were always useful and
contributed substantially to improving the quality of the final contributed substantially to improving the quality of the final
result. result.
James Lentini graciously read the rewrite of Section 7 and his
comments were vital in improving the quality of that effort.
Rob Thurlow, Sorin Faibish, James Lentini, Bruce Fields, and Trond
Myklebust were faithful attendants of the biweekly triage meeting and
accepted many an action item.
Appendix B. RFC Editor Notes Appendix B. RFC Editor Notes
[RFC Editor: please remove this section prior to publishing this [RFC Editor: please remove this section prior to publishing this
document as an RFC] document as an RFC]
[RFC Editor: prior to publishing this document as an RFC, please [RFC Editor: prior to publishing this document as an RFC, please
replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the
RFC number of this document] RFC number of this document]
Authors' Addresses Authors' Addresses
Thomas Haynes Thomas Haynes
Oracle NetApp
9110 E 66th St 9110 E 66th St
Tulsa, OK 74133 Tulsa, OK 74133
USA USA
Phone: +1 918 307 1415 Phone: +1 918 307 1415
Email: tom.haynes@oracle.com Email: thomas@netapp.com
David Noveck David Noveck
EMC EMC
32 Coslin Drive 32 Coslin Drive
Southborough, MA 01772 Southborough, MA 01772
US US
Phone: +1 508 305 8404 Phone: +1 508 305 8404
Email: novecd@emc.com Email: novecd@emc.com
 End of changes. 256 change blocks. 
636 lines changed or deleted 808 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/