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/ |