--- 1/draft-ietf-nfsv4-rfc3530bis-08.txt 2011-03-13 21:14:19.000000000 +0100 +++ 2/draft-ietf-nfsv4-rfc3530bis-09.txt 2011-03-13 21:14:20.000000000 +0100 @@ -1,18 +1,19 @@ -NFSv4 T. Haynes -Internet-Draft D. Noveck -Intended status: Standards Track Editors -Expires: September 5, 2011 March 04, 2011 +NFSv4 T. Haynes, Ed. +Internet-Draft NetApp +Intended status: Standards Track D. Noveck, Ed. +Expires: September 14, 2011 EMC + March 13, 2011 - NFS Version 4 Protocol - draft-ietf-nfsv4-rfc3530bis-08.txt + Network File System (NFS) Version 4 Protocol + draft-ietf-nfsv4-rfc3530bis-09.txt Abstract The Network File System (NFS) version 4 is a distributed filesystem protocol which owes heritage to NFS protocol version 2, RFC 1094, and version 3, RFC 1813. Unlike earlier versions, the NFS version 4 protocol supports traditional file access while integrating support for file locking and the mount protocol. In addition, support for strong security (and its negotiation), compound operations, client caching, and internationalization have been added. Of course, @@ -42,21 +43,21 @@ and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on September 5, 2011. + This Internet-Draft will expire on September 14, 2011. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -93,263 +94,263 @@ 1.5.4. OPEN and CLOSE . . . . . . . . . . . . . . . . . . . 14 1.5.5. File Locking . . . . . . . . . . . . . . . . . . . . 14 1.5.6. Client Caching and Delegation . . . . . . . . . . . 14 1.6. General Definitions . . . . . . . . . . . . . . . . . . 15 2. Protocol Data Types . . . . . . . . . . . . . . . . . . . . . 17 2.1. Basic Data Types . . . . . . . . . . . . . . . . . . . . 17 2.2. Structured Data Types . . . . . . . . . . . . . . . . . 19 3. RPC and Security Flavor . . . . . . . . . . . . . . . . . . . 24 3.1. Ports and Transports . . . . . . . . . . . . . . . . . . 24 3.1.1. Client Retransmission Behavior . . . . . . . . . . . 25 - 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 25 + 3.2. Security Flavors . . . . . . . . . . . . . . . . . . . . 26 3.2.1. Security mechanisms for NFSv4 . . . . . . . . . . . 26 3.3. Security Negotiation . . . . . . . . . . . . . . . . . . 28 - 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 28 - 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 28 + 3.3.1. SECINFO . . . . . . . . . . . . . . . . . . . . . . 29 + 3.3.2. Security Error . . . . . . . . . . . . . . . . . . . 29 3.3.3. Callback RPC Authentication . . . . . . . . . . . . 29 4. Filehandles . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.1. Obtaining the First Filehandle . . . . . . . . . . . . . 31 - 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 31 - 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 31 + 4.1.1. Root Filehandle . . . . . . . . . . . . . . . . . . 32 + 4.1.2. Public Filehandle . . . . . . . . . . . . . . . . . 32 4.2. Filehandle Types . . . . . . . . . . . . . . . . . . . . 32 - 4.2.1. General Properties of a Filehandle . . . . . . . . . 32 + 4.2.1. General Properties of a Filehandle . . . . . . . . . 33 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 33 - 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 33 + 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 34 4.2.4. One Method of Constructing a Volatile Filehandle . . 35 4.3. Client Recovery from Filehandle Expiration . . . . . . . 35 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 36 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 37 - 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 37 + 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 38 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 38 - 5.4. Classification of Attributes . . . . . . . . . . . . . . 39 + 5.4. Classification of Attributes . . . . . . . . . . . . . . 40 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 40 - 5.6. REQUIRED Attributes - List and Definition References . . 40 + 5.6. REQUIRED Attributes - List and Definition References . . 41 5.7. RECOMMENDED Attributes - List and Definition - References . . . . . . . . . . . . . . . . . . . . . . . 41 - 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 42 - 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 42 + References . . . . . . . . . . . . . . . . . . . . . . . 42 + 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 43 + 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 43 5.8.2. Definitions of Uncategorized RECOMMENDED - Attributes . . . . . . . . . . . . . . . . . . . . . 44 - 5.9. Interpreting owner and owner_group . . . . . . . . . . . 50 - 5.10. Character Case Attributes . . . . . . . . . . . . . . . 53 - 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 53 + Attributes . . . . . . . . . . . . . . . . . . . . . 45 + 5.9. Interpreting owner and owner_group . . . . . . . . . . . 51 + 5.10. Character Case Attributes . . . . . . . . . . . . . . . 54 + 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 54 6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 54 - 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 54 - 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 54 - 6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 68 - 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 69 - 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 69 - 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 70 - 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 71 + 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 55 + 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 55 + 6.2.2. Attribute 33: mode . . . . . . . . . . . . . . . . . 69 + 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 70 + 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 70 + 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 71 + 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 72 6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 72 - 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 73 - 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 73 - 7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 75 - 7.1. Location Attributes . . . . . . . . . . . . . . . . . . 75 + 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 74 + 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 74 + 7. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 76 + 7.1. Location Attributes . . . . . . . . . . . . . . . . . . 76 7.2. File System Presence or Absence . . . . . . . . . . . . 76 7.3. Getting Attributes for an Absent File System . . . . . . 77 - 7.3.1. GETATTR Within an Absent File System . . . . . . . . 77 - 7.3.2. READDIR and Absent File Systems . . . . . . . . . . 78 - 7.4. Uses of Location Information . . . . . . . . . . . . . . 78 - 7.4.1. File System Replication . . . . . . . . . . . . . . 79 - 7.4.2. File System Migration . . . . . . . . . . . . . . . 80 + 7.3.1. GETATTR Within an Absent File System . . . . . . . . 78 + 7.3.2. READDIR and Absent File Systems . . . . . . . . . . 79 + 7.4. Uses of Location Information . . . . . . . . . . . . . . 79 + 7.4.1. File System Replication . . . . . . . . . . . . . . 80 + 7.4.2. File System Migration . . . . . . . . . . . . . . . 81 7.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 81 - 7.5. Location Entries and Server Identity . . . . . . . . . . 81 - 7.6. Additional Client-Side Considerations . . . . . . . . . 82 - 7.7. Effecting File System Transitions . . . . . . . . . . . 83 - 7.7.1. File System Transitions and Simultaneous Access . . 84 - 7.7.2. Filehandles and File System Transitions . . . . . . 84 - 7.7.3. Fileids and File System Transitions . . . . . . . . 85 - 7.7.4. Fsids and File System Transitions . . . . . . . . . 86 - 7.7.5. The Change Attribute and File System Transitions . . 86 - 7.7.6. Lock State and File System Transitions . . . . . . . 87 - 7.7.7. Write Verifiers and File System Transitions . . . . 89 + 7.5. Location Entries and Server Identity . . . . . . . . . . 82 + 7.6. Additional Client-Side Considerations . . . . . . . . . 83 + 7.7. Effecting File System Transitions . . . . . . . . . . . 84 + 7.7.1. File System Transitions and Simultaneous Access . . 85 + 7.7.2. Filehandles and File System Transitions . . . . . . 85 + 7.7.3. Fileids and File System Transitions . . . . . . . . 86 + 7.7.4. Fsids and File System Transitions . . . . . . . . . 87 + 7.7.5. The Change Attribute and File System Transitions . . 87 + 7.7.6. Lock State and File System Transitions . . . . . . . 88 + 7.7.7. Write Verifiers and File System Transitions . . . . 90 7.7.8. Readdir Cookies and Verifiers and File System - Transitions . . . . . . . . . . . . . . . . . . . . 89 + Transitions . . . . . . . . . . . . . . . . . . . . 90 7.7.9. File System Data and File System Transitions . . . . 90 - 7.8. Effecting File System Referrals . . . . . . . . . . . . 91 - 7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 91 - 7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 95 + 7.8. Effecting File System Referrals . . . . . . . . . . . . 92 + 7.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 92 + 7.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 96 7.9. The Attribute fs_locations . . . . . . . . . . . . . . . 98 - 7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 99 + 7.9.1. Inferring Transition Modes . . . . . . . . . . . . . 100 8. NFS Server Name Space . . . . . . . . . . . . . . . . . . . . 101 - 8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 101 - 8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 101 - 8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 101 - 8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 102 - 8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 102 - 8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 102 - 8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 103 - 8.8. Security Policy and Name Space Presentation . . . . . . 103 - 9. File Locking and Share Reservations . . . . . . . . . . . . . 104 - 9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 105 - 9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 105 - 9.1.2. Server Release of Client ID . . . . . . . . . . . . 108 - 9.1.3. Stateid Definition . . . . . . . . . . . . . . . . . 109 + 8.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 102 + 8.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 102 + 8.3. Server Pseudo Filesystem . . . . . . . . . . . . . . . . 102 + 8.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 103 + 8.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 103 + 8.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 103 + 8.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 104 + 8.8. Security Policy and Name Space Presentation . . . . . . 104 + 9. File Locking and Share Reservations . . . . . . . . . . . . . 105 + 9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 106 + 9.1.1. Client ID . . . . . . . . . . . . . . . . . . . . . 106 + 9.1.2. Server Release of Client ID . . . . . . . . . . . . 109 + 9.1.3. Stateid Definition . . . . . . . . . . . . . . . . . 110 9.1.4. lock_owner . . . . . . . . . . . . . . . . . . . . . 117 - 9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 117 - 9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 119 - 9.1.7. Recovery from Replayed Requests . . . . . . . . . . 120 + 9.1.5. Use of the Stateid and Locking . . . . . . . . . . . 118 + 9.1.6. Sequencing of Lock Requests . . . . . . . . . . . . 120 + 9.1.7. Recovery from Replayed Requests . . . . . . . . . . 121 9.1.8. Releasing lock_owner State . . . . . . . . . . . . . 121 - 9.1.9. Use of Open Confirmation . . . . . . . . . . . . . . 121 - 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 122 + 9.1.9. Use of Open Confirmation . . . . . . . . . . . . . . 122 + 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 123 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 123 - 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 123 - 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 124 - 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 125 - 9.6.1. Client Failure and Recovery . . . . . . . . . . . . 125 - 9.6.2. Server Failure and Recovery . . . . . . . . . . . . 126 - 9.6.3. Network Partitions and Recovery . . . . . . . . . . 127 - 9.7. Recovery from a Lock Request Timeout or Abort . . . . . 133 - 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 133 - 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 135 - 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 135 - 9.10.1. Close and Retention of State Information . . . . . . 136 - 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 137 - 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 137 + 9.4. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 124 + 9.5. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 125 + 9.6. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 126 + 9.6.1. Client Failure and Recovery . . . . . . . . . . . . 126 + 9.6.2. Server Failure and Recovery . . . . . . . . . . . . 127 + 9.6.3. Network Partitions and Recovery . . . . . . . . . . 128 + 9.7. Recovery from a Lock Request Timeout or Abort . . . . . 134 + 9.8. Server Revocation of Locks . . . . . . . . . . . . . . . 135 + 9.9. Share Reservations . . . . . . . . . . . . . . . . . . . 136 + 9.10. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 136 + 9.10.1. Close and Retention of State Information . . . . . . 137 + 9.11. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 138 + 9.12. Short and Long Leases . . . . . . . . . . . . . . . . . 139 9.13. Clocks, Propagation Delay, and Calculating Lease - Expiration . . . . . . . . . . . . . . . . . . . . . . . 138 - 9.14. Migration, Replication and State . . . . . . . . . . . . 138 - 9.14.1. Migration and State . . . . . . . . . . . . . . . . 139 - 9.14.2. Replication and State . . . . . . . . . . . . . . . 140 - 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 140 - 9.14.4. Migration and the Lease_time Attribute . . . . . . . 141 - 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 141 - 10.1. Performance Challenges for Client-Side Caching . . . . . 142 - 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 143 - 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 145 - 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 147 - 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 147 - 10.3.2. Data Caching and File Locking . . . . . . . . . . . 148 - 10.3.3. Data Caching and Mandatory File Locking . . . . . . 149 - 10.3.4. Data Caching and File Identity . . . . . . . . . . . 150 + Expiration . . . . . . . . . . . . . . . . . . . . . . . 139 + 9.14. Migration, Replication and State . . . . . . . . . . . . 140 + 9.14.1. Migration and State . . . . . . . . . . . . . . . . 140 + 9.14.2. Replication and State . . . . . . . . . . . . . . . 141 + 9.14.3. Notification of Migrated Lease . . . . . . . . . . . 141 + 9.14.4. Migration and the Lease_time Attribute . . . . . . . 142 + 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 143 + 10.1. Performance Challenges for Client-Side Caching . . . . . 143 + 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 144 + 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 146 + 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 148 + 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 148 + 10.3.2. Data Caching and File Locking . . . . . . . . . . . 149 + 10.3.3. Data Caching and Mandatory File Locking . . . . . . 151 + 10.3.4. Data Caching and File Identity . . . . . . . . . . . 151 - 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 151 - 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 153 - 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 155 - 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 155 - 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 158 - 10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 160 - 10.4.6. Clients that Fail to Honor Delegation Recalls . . . 161 - 10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 162 - 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 162 - 10.5.1. Revocation Recovery for Write Open Delegation . . . 163 - 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 163 - 10.7. Data and Metadata Caching and Memory Mapped Files . . . 165 - 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 167 - 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 168 - 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 169 - 12. Internationalization . . . . . . . . . . . . . . . . . . . . 172 - 12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 173 - 12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 173 - 12.1.2. Normalization, Equivalence, and Confusability . . . 174 - 12.2. String Type Overview . . . . . . . . . . . . . . . . . . 177 - 12.2.1. Overall String Class Divisions . . . . . . . . . . . 177 - 12.2.2. Divisions by Typedef Parent types . . . . . . . . . 178 - 12.2.3. Individual Types and Their Handling . . . . . . . . 179 - 12.3. Errors Related to Strings . . . . . . . . . . . . . . . 180 - 12.4. Types with Pre-processing to Resolve Mixture Issues . . 181 - 12.4.1. Processing of Principal Strings . . . . . . . . . . 181 - 12.4.2. Processing of Server Id Strings . . . . . . . . . . 181 - 12.5. String Types without Internationalization Processing . . 182 - 12.6. Types with Processing Defined by Other Internet Areas . 182 - 12.7. String Types with NFS-specific Processing . . . . . . . 183 - 12.7.1. Handling of File Name Components . . . . . . . . . . 184 - 12.7.2. Processing of Link Text . . . . . . . . . . . . . . 193 - 12.7.3. Processing of Principal Prefixes . . . . . . . . . . 194 - 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 195 - 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 195 - 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 197 - 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 198 - 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 199 - 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 200 - 13.1.5. State Management Errors . . . . . . . . . . . . . . 202 - 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 203 - 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 203 - 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 204 - 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 205 - 13.1.10. Client Management Errors . . . . . . . . . . . . . . 206 - 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 206 - 13.2. Operations and their valid errors . . . . . . . . . . . 207 - 13.3. Callback operations and their valid errors . . . . . . . 214 - 13.4. Errors and the operations that use them . . . . . . . . 214 - 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 219 - 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 219 - 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 220 - 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 221 - 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 221 - 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 221 - 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 221 - 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 222 - 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 227 - 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 230 - 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 231 - 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 233 + 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 152 + 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 155 + 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 156 + 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 156 + 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 159 + 10.4.5. OPEN Delegation Race with CB_RECALL . . . . . . . . 161 + 10.4.6. Clients that Fail to Honor Delegation Recalls . . . 162 + 10.4.7. Delegation Revocation . . . . . . . . . . . . . . . 163 + 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 163 + 10.5.1. Revocation Recovery for Write Open Delegation . . . 164 + 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 164 + 10.7. Data and Metadata Caching and Memory Mapped Files . . . 166 + 10.8. Name Caching . . . . . . . . . . . . . . . . . . . . . . 169 + 10.9. Directory Caching . . . . . . . . . . . . . . . . . . . 170 + 11. Minor Versioning . . . . . . . . . . . . . . . . . . . . . . 171 + 12. Internationalization . . . . . . . . . . . . . . . . . . . . 173 + 12.1. Use of UTF-8 . . . . . . . . . . . . . . . . . . . . . . 174 + 12.1.1. Relation to Stringprep . . . . . . . . . . . . . . . 174 + 12.1.2. Normalization, Equivalence, and Confusability . . . 175 + 12.2. String Type Overview . . . . . . . . . . . . . . . . . . 178 + 12.2.1. Overall String Class Divisions . . . . . . . . . . . 178 + 12.2.2. Divisions by Typedef Parent types . . . . . . . . . 179 + 12.2.3. Individual Types and Their Handling . . . . . . . . 180 + 12.3. Errors Related to Strings . . . . . . . . . . . . . . . 181 + 12.4. Types with Pre-processing to Resolve Mixture Issues . . 182 + 12.4.1. Processing of Principal Strings . . . . . . . . . . 182 + 12.4.2. Processing of Server Id Strings . . . . . . . . . . 183 + 12.5. String Types without Internationalization Processing . . 183 + 12.6. Types with Processing Defined by Other Internet Areas . 184 + 12.7. String Types with NFS-specific Processing . . . . . . . 185 + 12.7.1. Handling of File Name Components . . . . . . . . . . 185 + 12.7.2. Processing of Link Text . . . . . . . . . . . . . . 194 + 12.7.3. Processing of Principal Prefixes . . . . . . . . . . 195 + 13. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 196 + 13.1. Error Definitions . . . . . . . . . . . . . . . . . . . 196 + 13.1.1. General Errors . . . . . . . . . . . . . . . . . . . 198 + 13.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 199 + 13.1.3. Compound Structure Errors . . . . . . . . . . . . . 201 + 13.1.4. File System Errors . . . . . . . . . . . . . . . . . 201 + 13.1.5. State Management Errors . . . . . . . . . . . . . . 203 + 13.1.6. Security Errors . . . . . . . . . . . . . . . . . . 204 + 13.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 205 + 13.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 205 + 13.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 207 + 13.1.10. Client Management Errors . . . . . . . . . . . . . . 207 + 13.1.11. Attribute Handling Errors . . . . . . . . . . . . . 208 + 13.2. Operations and their valid errors . . . . . . . . . . . 208 + 13.3. Callback operations and their valid errors . . . . . . . 216 + 13.4. Errors and the operations that use them . . . . . . . . 216 + 14. NFSv4 Requests . . . . . . . . . . . . . . . . . . . . . . . 220 + 14.1. Compound Procedure . . . . . . . . . . . . . . . . . . . 221 + 14.2. Evaluation of a Compound Request . . . . . . . . . . . . 221 + 14.3. Synchronous Modifying Operations . . . . . . . . . . . . 222 + 14.4. Operation Values . . . . . . . . . . . . . . . . . . . . 223 + 15. NFSv4 Procedures . . . . . . . . . . . . . . . . . . . . . . 223 + 15.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 223 + 15.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 223 + 15.3. Operation 3: ACCESS - Check Access Rights . . . . . . . 229 + 15.4. Operation 4: CLOSE - Close File . . . . . . . . . . . . 231 + 15.5. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 232 + 15.6. Operation 6: CREATE - Create a Non-Regular File Object . 235 15.7. Operation 7: DELEGPURGE - Purge Delegations Awaiting - Recovery . . . . . . . . . . . . . . . . . . . . . . . . 236 - 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 237 - 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 237 - 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 239 - 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 240 - 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 241 - 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 245 - 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 247 - 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 248 - 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 250 + Recovery . . . . . . . . . . . . . . . . . . . . . . . . 238 + 15.8. Operation 8: DELEGRETURN - Return Delegation . . . . . . 239 + 15.9. Operation 9: GETATTR - Get Attributes . . . . . . . . . 239 + 15.10. Operation 10: GETFH - Get Current Filehandle . . . . . . 241 + 15.11. Operation 11: LINK - Create Link to a File . . . . . . . 242 + 15.12. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 243 + 15.13. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 247 + 15.14. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 249 + 15.15. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 250 + 15.16. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 252 15.17. Operation 17: NVERIFY - Verify Difference in - Attributes . . . . . . . . . . . . . . . . . . . . . . . 250 - 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 252 + Attributes . . . . . . . . . . . . . . . . . . . . . . . 252 + 15.18. Operation 18: OPEN - Open a Regular File . . . . . . . . 254 15.19. Operation 19: OPENATTR - Open Named Attribute - Directory . . . . . . . . . . . . . . . . . . . . . . . 262 - 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 263 - 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 265 - 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 266 - 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 267 - 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 268 - 15.25. Operation 25: READ - Read from File . . . . . . . . . . 269 - 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 271 - 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 275 - 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 276 - 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 278 - 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 280 - 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 281 - 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 282 - 15.33. Operation 33: SECINFO - Obtain Available Security . . . 282 - 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 285 - 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 288 - 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 292 - 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 295 - 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 297 + Directory . . . . . . . . . . . . . . . . . . . . . . . 264 + 15.20. Operation 20: OPEN_CONFIRM - Confirm Open . . . . . . . 265 + 15.21. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 267 + 15.22. Operation 22: PUTFH - Set Current Filehandle . . . . . . 268 + 15.23. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 269 + 15.24. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 270 + 15.25. Operation 25: READ - Read from File . . . . . . . . . . 271 + 15.26. Operation 26: READDIR - Read Directory . . . . . . . . . 273 + 15.27. Operation 27: READLINK - Read Symbolic Link . . . . . . 277 + 15.28. Operation 28: REMOVE - Remove Filesystem Object . . . . 278 + 15.29. Operation 29: RENAME - Rename Directory Entry . . . . . 280 + 15.30. Operation 30: RENEW - Renew a Lease . . . . . . . . . . 282 + 15.31. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 283 + 15.32. Operation 32: SAVEFH - Save Current Filehandle . . . . . 284 + 15.33. Operation 33: SECINFO - Obtain Available Security . . . 284 + 15.34. Operation 34: SETATTR - Set Attributes . . . . . . . . . 287 + 15.35. Operation 35: SETCLIENTID - Negotiate Client ID . . . . 290 + 15.36. Operation 36: SETCLIENTID_CONFIRM - Confirm Client ID . 294 + 15.37. Operation 37: VERIFY - Verify Same Attributes . . . . . 297 + 15.38. Operation 38: WRITE - Write to File . . . . . . . . . . 299 15.39. Operation 39: RELEASE_LOCKOWNER - Release Lockowner - State . . . . . . . . . . . . . . . . . . . . . . . . . 301 - 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 302 - 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 302 - 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 303 - 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 303 - 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 305 - 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 306 + State . . . . . . . . . . . . . . . . . . . . . . . . . 303 + 15.40. Operation 10044: ILLEGAL - Illegal operation . . . . . . 304 + 16. NFSv4 Callback Procedures . . . . . . . . . . . . . . . . . . 304 + 16.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 305 + 16.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 305 + 16.2.6. Operation 3: CB_GETATTR - Get Attributes . . . . . . 307 + 16.2.7. Operation 4: CB_RECALL - Recall an Open Delegation . 308 16.2.8. Operation 10044: CB_ILLEGAL - Illegal Callback - Operation . . . . . . . . . . . . . . . . . . . . . 307 - 17. Security Considerations . . . . . . . . . . . . . . . . . . . 308 - 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 309 - 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 309 - 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 310 - 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 310 - 18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 310 - 18.2.1. Initial Registry . . . . . . . . . . . . . . . . . . 312 - 18.2.2. Updating Registrations . . . . . . . . . . . . . . . 312 - 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 312 - 19.1. Normative References . . . . . . . . . . . . . . . . . . 312 - 19.2. Informative References . . . . . . . . . . . . . . . . . 313 - Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 315 - Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 316 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 316 + Operation . . . . . . . . . . . . . . . . . . . . . 309 + 17. Security Considerations . . . . . . . . . . . . . . . . . . . 310 + 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 311 + 18.1. Named Attribute Definitions . . . . . . . . . . . . . . 311 + 18.1.1. Initial Registry . . . . . . . . . . . . . . . . . . 312 + 18.1.2. Updating Registrations . . . . . . . . . . . . . . . 312 + 18.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 312 + 18.2.1. Initial Registry . . . . . . . . . . . . . . . . . . 314 + 18.2.2. Updating Registrations . . . . . . . . . . . . . . . 314 + 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 314 + 19.1. Normative References . . . . . . . . . . . . . . . . . . 314 + 19.2. Informative References . . . . . . . . . . . . . . . . . 315 + Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 317 + Appendix B. RFC Editor Notes . . . . . . . . . . . . . . . . . . 318 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 318 1. Introduction 1.1. Changes since RFC 3530 This document, together with the companion XDR description document [2], obsoletes RFC 3530 [11] as the authoritative document describing NFSv4. It does not introduce any over-the-wire protocol changes, in the sense that previously valid requests requests remain valid. However, some requests previously defined as invalid, although not @@ -377,21 +378,21 @@ reality of required string processing. o LIPKEY SPKM/3 has been moved from being REQUIRED to OPTIONAL. o Some clarification on a client re-establishing callback information to the new server if state has been migrated. o A third edge case was added for Courtesy locks and network partitions. - o The definintion of stateid was strengthened, which had the side + o The definition of stateid was strengthened, which had the side effect of introducing a semantic change in a COMPOUND structure having a current stateid and a saved stateid. 1.2. Changes since RFC 3010 This definition of the NFSv4 protocol replaces or obsoletes the definition present in [12]. While portions of the two documents have remained the same, there have been substantive changes in others. The changes made between [12] and this document represent implementation experience and further review of the protocol. While @@ -705,92 +706,92 @@ exist, then delegations cannot be granted. The essence of a delegation is that it allows the client to locally service operations such as OPEN, CLOSE, LOCK, LOCKU, READ, or WRITE without immediate interaction with the server. 1.6. General Definitions The following definitions are provided for the purpose of providing an appropriate context for the reader. - Byte In this document, a byte is an octet, i.e., a datum exactly 8 + Byte: In this document, a byte is an octet, i.e., a datum exactly 8 bits in length. - Client The client is the entity that accesses the NFS server's + Client: The client is the entity that accesses the NFS server's resources. The client may be an application that contains the logic to access the NFS server directly. The client may also be the traditional operating system client that provides remote filesystem services for a set of applications. With reference to byte-range locking, the client is also the entity that maintains a set of locks on behalf of one or more applications. This client is responsible for crash or failure recovery for those locks it manages. Note that multiple clients may share the same transport and connection and multiple clients may exist on the same network node. - Client ID A 64-bit quantity used as a unique, short-hand reference + Client ID: A 64-bit quantity used as a unique, short-hand reference to a client supplied Verifier and ID. The server is responsible for supplying the Client ID. - File System The file system is the collection of objects on a server - that share the same fsid attribute (see Section 5.8.1.9). + File System: The file system is the collection of objects on a + server that share the same fsid attribute (see Section 5.8.1.9). - Lease An interval of time defined by the server for which the client - is irrevocably granted a lock. At the end of a lease period the - lock may be revoked if the lease has not been extended. The lock - must be revoked if a conflicting lock has been granted after the - lease interval. + Lease: An interval of time defined by the server for which the + client is irrevocably granted a lock. At the end of a lease + period the lock may be revoked if the lease has not been extended. + The lock must be revoked if a conflicting lock has been granted + after the lease interval. All leases granted by a server have the same fixed interval. Note that the fixed interval was chosen to alleviate the expense a server would have in maintaining state about variable length leases across server failures. - Lock The term "lock" is used to refer to both record (byte-range) + Lock: The term "lock" is used to refer to both record (byte-range) locks as well as share reservations unless specifically stated otherwise. - Server The "Server" is the entity responsible for coordinating + Server: The "Server" is the entity responsible for coordinating client access to a set of filesystems. - Stable Storage NFSv4 servers must be able to recover without data + Stable Storage: NFSv4 servers must be able to recover without data loss from multiple power failures (including cascading power failures, that is, several power failures in quick succession), operating system failures, and hardware failure of components other than the storage medium itself (for example, disk, nonvolatile RAM). Some examples of stable storage that are allowable for an NFS server include: - 1. Media commit of data, that is, the modified data has been + (1) Media commit of data, that is, the modified data has been successfully written to the disk media, for example, the disk platter. - 2. An immediate reply disk drive with battery-backed on-drive + (2) An immediate reply disk drive with battery-backed on-drive intermediate storage or uninterruptible power system (UPS). - 3. Server commit of data with battery-backed intermediate storage - and recovery software. + (3) Server commit of data with battery-backed intermediate + storage and recovery software. - 4. Cache commit with uninterruptible power system (UPS) and + (4) Cache commit with uninterruptible power system (UPS) and recovery software. - Stateid A stateid is a 128-bit quantity returned by a server that + Stateid: A stateid is a 128-bit quantity returned by a server that uniquely defines the open and locking states provided by the server for a specific open-owner or lock-owner/open-owner pair for a specific file and type of lock. - Verifier A 64-bit quantity generated by the client that the server + Verifier: A 64-bit quantity generated by the client that the server can use to determine if the client has restarted and lost all previous lock state. 2. Protocol Data Types The syntax and semantics to describe the data types of the NFS version 4 protocol are defined in the XDR [15] and RPC [3] documents. The next sections build upon the XDR data types to define types and structures specific to this protocol. @@ -1575,39 +1579,39 @@ server should return NFS4ERR_STALE to the client (as is the case for persistent filehandles). In all other cases where the server determines that a volatile filehandle can no longer be used, it should return an error of NFS4ERR_FHEXPIRED. The mandatory attribute "fh_expire_type" is used by the client to determine what type of filehandle the server is providing for a particular filesystem. This attribute is a bitmask with the following values: - FH4_PERSISTENT The value of FH4_PERSISTENT is used to indicate a + FH4_PERSISTENT: The value of FH4_PERSISTENT is used to indicate a persistent filehandle, which is valid until the object is removed from the filesystem. The server will not return NFS4ERR_FHEXPIRED for this filehandle. FH4_PERSISTENT is defined as a value in which none of the bits specified below are set. - FH4_VOLATILE_ANY The filehandle may expire at any time, except as + FH4_VOLATILE_ANY: The filehandle may expire at any time, except as specifically excluded (i.e., FH4_NOEXPIRE_WITH_OPEN). - FH4_NOEXPIRE_WITH_OPEN May only be set when FH4_VOLATILE_ANY is set. - If this bit is set, then the meaning of FH4_VOLATILE_ANY is + FH4_NOEXPIRE_WITH_OPEN: May only be set when FH4_VOLATILE_ANY is + set. If this bit is set, then the meaning of FH4_VOLATILE_ANY is qualified to exclude any expiration of the filehandle when it is open. - FH4_VOL_MIGRATION The filehandle will expire as a result of + FH4_VOL_MIGRATION: The filehandle will expire as a result of migration. If FH4_VOLATILE_ANY is set, FH4_VOL_MIGRATION is redundant. - FH4_VOL_RENAME The filehandle will expire during rename. This + FH4_VOL_RENAME: The filehandle will expire during rename. This includes a rename by the requesting client or a rename by any other client. If FH4_VOLATILE_ANY is set, FH4_VOL_RENAME is redundant. Servers which provide volatile filehandles that may expire while open (i.e., if FH4_VOL_MIGRATION or FH4_VOL_RENAME is set or if FH4_VOLATILE_ANY is set and FH4_NOEXPIRE_WITH_OPEN not set), should deny a RENAME or REMOVE that would affect an OPEN file of any of the components leading to the OPEN file. In addition, the server should deny all RENAME or REMOVE requests during the grace period upon @@ -3888,20 +3890,31 @@ Another issue concerns refresh of referral locations. When referrals are used extensively, they may change as server configurations change. It is expected that clients will cache information related to traversing referrals so that future client-side requests are resolved locally without server communication. This is usually rooted in client-side name look up caching. Clients should periodically purge this data for referral points in order to detect changes in location information. + A problem exists if a client allows an open owner to have state on + multiple filesystems on a server. If one of those filesystems is + migrated, what happens to the sequence numbers? A client can avoid + such a situation with the stipulation that any client which supports + migration MUST ensure that any open owner is confined to a single + filesystem. If the server finds itself migrating open owners that + span multiple filesystems, then it MUST not migrate the state for the + conflicting open owners on the non-migrated filesystems; instead it + MUST return NFS4ERR_STALE_STATEID if the client tries to use those + stateids. + 7.7. Effecting File System Transitions Transitions between file system instances, whether due to switching between replicas upon server unavailability or to server-initiated migration events, are best dealt with together. This is so even though, for the server, pragmatic considerations will normally force different implementation strategies for planned and unplanned transitions. Even though the prototypical use cases of replication and migration contain distinctive sets of features, when all possibilities for these operations are considered, there is an @@ -5239,22 +5248,22 @@ in the case of a stateid sent with a READ or WRITE operation. It also may set a non-zero value, in which case the server checks if that seqid is the correct one. In that case, the server is required to return NFS4ERR_OLD_STATEID if the seqid is lower than the most current value and NFS4ERR_BAD_STATEID if the seqid is greater than the most current value. This would be the common choice in the case of stateids sent with a CLOSE or OPEN_DOWNGRADE. Because OPENs may be sent in parallel for the same owner, a client might close a file without knowing that an OPEN upgrade had been done by the server, changing the lock in question. If CLOSE were sent with a zero seqid, - the OPEN upgrade would be cancelled before the client even received - an indication that an upgrade had happened. + the OPEN upgrade would be canceled before the client even received an + indication that an upgrade had happened. When a stateid is sent by the server to the client as part of a callback operation, it is not subject to checking for a current seqid and returning NFS4ERR_OLD_STATEID. This is because the client is not in a position to know the most up-to-date seqid and thus cannot verify it. Unless specially noted, the seqid value for a stateid sent by the server to the client as part of a callback is required to be zero with NFS4ERR_BAD_STATEID returned if it is not. In making comparisons between seqids, both by the client in @@ -6031,34 +6040,37 @@ the client with the now invalid stateids will fail with the server returning the error NFS4ERR_EXPIRED. Once this error is received, the client will suitably notify the application that held the lock. 9.6.3.1. Courtesy Locks As a courtesy to the client or as an optimization, the server may continue to hold locks on behalf of a client for which recent communication has extended beyond the lease period. If the server receives a lock or I/O request that conflicts with one of these - courtesy locks, the server must free the courtesy lock and grant the - new request. + courtesy locks, the server MUST free the courtesy lock and grant the + new request. If the server runs out of resources, it MAY free all + courtesy locks. I.e., the client MUST not make an assumption that + the server has issued courtesy locks. If the server does not reboot before the network partition is healed, when the original client tries to access a courtesy lock which was freed, the server SHOULD send back a NFS4ERR_BAD_STATEID to the client. If the client tries to access a courtesy lock which was not - freed, then the server should mark all of the courtesy locks as + freed, then the server SHOULD mark all of the courtesy locks as implicitly being renewed. - When a network partition is combined with a server reboot, there are - edge conditions that place requirements on the server in order to - avoid silent data corruption following the server reboot. Two of - these edge conditions are known, and are discussed below. + When a network partition is combined with a server reboot, then both + the server and client have responsibilities to ensure that the client + does not reclaim a lock which it should no longer be able to access. + The next sections illustrate examples of these edge conditions and + the steps necessary to be undertaken to ensure proper lock semantics. 9.6.3.1.1. First Server Edge Condition The first edge condition has the following scenario: 1. Client A acquires a lock. 2. Client A and server experience mutual network partition, such that client A is unable to renew its lease. @@ -6197,41 +6210,51 @@ 4. Client A issues a RENEW operation, and gets back a NFS4ERR_STALE_CLIENTID. 5. Client A reclaims its lock 1 within the server's grace period. 6. Client A and server experience mutual network partition, such that client A is unable to reclaim its remaining locks within the grace period. - 7. Server's reclaim grace period ends. Client A has no locks - recorded on server. + 7. Server's reclaim grace period ends. - 8. Server reboots a second time. + 8. Client B acquires a lock that would have conflicted with Client + A's lock 2. - 9. Network partition between client A and server heals. + 9. Client B releases the lock. - 10. Client A issues a RENEW operation, and gets back a + 10. Server reboots a second time. + + 11. Network partition between client A and server heals. + + 12. Client A issues a RENEW operation, and gets back a NFS4ERR_STALE_CLIENTID. - 11. Client A reclaims its lock 1 within the server's grace period. + 13. Client A reclaims both lock 1 and lock 2 within the server's + grace period. - During the partition, client A decided that the server had revoked - lock 2. After the partition, it was able to reclaim lock 1, but made - no attempt to reclaim lock 2. After the grace period, it is free to - try to reestablish lock 2 via LOCK operations. + At the last step, the client reclaims lock 2 as if it had held that + lock continuously, when in fact a conflicting lock was granted to + client B. - Note that the other two edge conditions are able to interact with - this third edge condition. Another client B may have established a - conflicting lock during the partition, made some changes, and the - released the lock before the second server reboot. + A server could avoid this situation by rejecting the reclaim of lock + 2. However, to do so accurately it would have to ensure that + additional information about individual locks held survives reboot. + Server implementations are not required to do that, so the client + must not assume that the server will. + + Instead, a client MUST reclaim only those locks which it succesfully + acquired from the previous server instance, omitting any that it + failed to reclaim before a new reboot. Thus, in the last step above, + client A should reclaim only lock 1. 9.6.3.1.5. Client's Handling of NFS4ERR_NO_GRACE A mandate for the client's handling of the NFS4ERR_NO_GRACE error is outside the scope of this specification, since the strategies for such handling are very dependent on the client's operating environment. However, one potential approach is described below. When the client receives NFS4ERR_NO_GRACE, it could examine the change attribute of the objects the client is trying to reclaim state @@ -8036,24 +8059,24 @@ 11. Minor Versioning To address the requirement of an NFS protocol that can evolve as the need arises, the NFSv4 protocol contains the rules and framework to allow for future minor changes or versioning. The base assumption with respect to minor versioning is that any future accepted minor version must follow the IETF process and be documented in a standards track RFC. Therefore, each minor version - number will correspond to an RFC. Minor version zero of the NFS - version 4 protocol is represented by this RFC. The COMPOUND and - CB_COMPOUND procedures support the encoding of the minor version - being requested by the client. + number will correspond to an RFC. Minor version 0 of the NFS version + 4 protocol is represented by this RFC. The COMPOUND and CB_COMPOUND + procedures support the encoding of the minor version being requested + by the client. The following items represent the basic rules for the development of minor versions. Note that a future minor version may decide to modify or add to the following rules as part of the minor version definition. 1. Procedures are not added or deleted To maintain the general RPC model, NFSv4 minor versions will not add to or delete procedures from the NFS program. @@ -8129,21 +8152,21 @@ 2. Minor versions may declare that a flag bit or enumeration value MUST NOT be implemented. 9. Minor versions may downgrade features from REQUIRED to RECOMMENDED, or RECOMMENDED to OPTIONAL. 10. Minor versions may upgrade features from OPTIONAL to RECOMMENDED or RECOMMENDED to REQUIRED. 11. A client and server that support minor version X SHOULD support - minor versions 0 (zero) through X-1 as well. + minor versions 0 through X-1 as well. 12. Except for infrastructural changes, no new features may be introduced as REQUIRED in a minor version. This rule allows for the introduction of new functionality and forces the use of implementation experience before designating a feature as REQUIRED. On the other hand, some classes of features are infrastructural and have broad effects. Allowing infrastructural features to be RECOMMENDED or OPTIONAL complicates implementation of the minor version. @@ -8403,39 +8427,39 @@ the responsibility of other IETF groups and our job is simply to reference those and perhaps make a few choices as to how they are to be used (e.g., U-labels vs. A-labels). o There are also cases in which a string has a small amount of NFSv4 processing which results in one or more strings being referred to one of the other categories. 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 internationalization handling mode or divides the string into a set of (two) strings with a different mode internationalization handling for each. The details are discussed in the section "Types with Pre-processing to Resolve Mixture 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 specifics of the various string types handled in this way are described in the section "String Types without 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 governed by non-NFS-specific internet specifications. The details are discussed in the section "Types with Processing Defined by Other Internet Areas". - NFS indicating that the string needs to be processed in a fashion + NFS: indicating that the string needs to be processed in a fashion governed by NFSv4-specific considerations. The primary focus is on enabling flexibility for the various file systems to be accessed and is described in the section "String Types with NFS- specific Processing". 12.2.2. Divisions by Typedef Parent types There are a number of different string types within NFSv4 and internationalization handling will be different for different types of strings. Each the types will be in one of four groups based on @@ -8624,36 +8649,36 @@ There are a number of types of strings which, for a number of different reasons, do not require any internationalization-specific handling, such as validation of UTF-8, normalization, or character mapping or checking. This does not necessarily mean that the strings need not be UTF-8. In some case, other checking on the string ensures that they are valid UTF-8, without doing any checking specific to internationalization. The following are the specific types: - comptag4 strings are an aid to debugging and the sender should avoid - confusion by not using anything but valid UTF-8. But any work - validating the string or modifying it would only add complication - to a mechanism whose basic function is best supported by making it - not subject to any checking and having data maximally available to - be looked at in a network trace. + comptag4: strings are an aid to debugging and the sender should + avoid confusion by not using anything but valid UTF-8. But any + work validating the string or modifying it would only add + complication to a mechanism whose basic function is best supported + by making it not subject to any checking and having data maximally + available to 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 processing specific to internationalization is required since anything that does not match is invalid and anything which does not obey the rules of UTF-8 will not be ASCII and consequently will not match, and will be invalid. - svraddr4 strings, in order to be valid, need to be ASCII, but if you - check them for validity, you have inherently checked that that + svraddr4: strings, in order to be valid, need to be ASCII, but if + you check them for validity, you have inherently checked that that they are ASCII and thus UTF-8. 12.6. Types with Processing Defined by Other Internet Areas There are two types of strings which NFSv4 deals with whose processing is defined by other Internet standards, and where issues related to different handling choices by server operating systems or server file systems do not apply. These are as follows: @@ -10796,33 +10824,33 @@ ACCESS4_READ even if it could have reliably checked other values. The results of this operation are necessarily advisory in nature. A return status of NFS4_OK and the appropriate bit set in the bit mask does not imply that such access will be allowed to the file system object in the future. This is because access rights can be revoked by the server at any time. The following access permissions may be requested: - ACCESS4_READ Read data from file or read a directory. + ACCESS4_READ: Read data from file or read a directory. - ACCESS4_LOOKUP Look up a name in a directory (no meaning for non- + ACCESS4_LOOKUP: Look up a name in a directory (no meaning for non- directory objects). - ACCESS4_MODIFY Rewrite existing file data or modify existing + ACCESS4_MODIFY: Rewrite existing file data or modify existing directory entries. - ACCESS4_EXTEND Write new data or add directory entries. + ACCESS4_EXTEND: Write new data or add directory entries. - ACCESS4_DELETE Delete an existing directory entry. + ACCESS4_DELETE: Delete an existing directory entry. - ACCESS4_EXECUTE Execute file (no meaning for a directory). + ACCESS4_EXECUTE: Execute file (no meaning for a directory). On success, the current filehandle retains its value. 15.3.5. IMPLEMENTATION In general, it is not sufficient for the client to attempt to deduce access permissions by inspecting the uid, gid, and mode fields in the file attributes or by attempting to interpret the contents of the ACL attribute. This is because the server may perform uid or gid mapping or enforce additional access control restrictions. It is also @@ -12131,34 +12159,34 @@ In the case that the client is recovering state from a server failure, the claim field of the OPEN argument is used to signify that the request is meant to reclaim state previously held. The "claim" field of the OPEN argument is used to specify the file to be opened and the state information which the client claims to possess. There are four basic claim types which cover the various situations for an OPEN. They are as follows: - CLAIM_NULL For the client, this is a new OPEN request and there is + CLAIM_NULL: For the client, this is a new OPEN request and there is no previous state associate with the file for the client. - CLAIM_PREVIOUS The client is claiming basic OPEN state for a file + CLAIM_PREVIOUS: The client is claiming basic OPEN state for a file that was held previous to a server reboot. Generally used when a server is returning persistent filehandles; the client may not have the file name to reclaim the OPEN. - CLAIM_DELEGATE_CUR The client is claiming a delegation for OPEN as + CLAIM_DELEGATE_CUR: The client is claiming a delegation for OPEN as granted by the server. Generally this is done as part of recalling a delegation. - CLAIM_DELEGATE_PREV The client is claiming a delegation granted to a - previous client instance; used after the client reboots. The + CLAIM_DELEGATE_PREV: The client is claiming a delegation granted to + a previous client instance; used after the client reboots. The server MAY support CLAIM_DELEGATE_PREV. If it does support CLAIM_DELEGATE_PREV, SETCLIENTID_CONFIRM MUST NOT remove the client's delegation state, and the server MUST support the DELEGPURGE operation. For OPEN requests whose claim type is other than CLAIM_PREVIOUS (i.e., requests other than those devoted to reclaiming opens after a server reboot) that reach the server during its grace or lease expiration period, the server returns an error of NFS4ERR_GRACE. @@ -14589,27 +14617,27 @@ must be done with the publication of an RFC. The initial values for this registry are as follows (some of this text is replicated from section 2.2 for clarity): The Network Identifier (or r_netid for short) is used to specify a transport protocol and associated universal address (or r_addr for short). The syntax of the Network Identifier is a US-ASCII string. The initial definitions for r_netid are: - "tcp" TCP over IP version 4 + "tcp": TCP over IP version 4 - "udp" UDP over IP version 4 + "udp": UDP over IP version 4 - "tcp6" TCP over IP version 6 + "tcp6": TCP over IP version 6 - "udp6" UDP over IP version 6 + "udp6": UDP over IP version 6 Note: the '"' marks are used for delimiting the strings for this document and are not part of the Network Identifier string. For the "tcp" and "udp" Network Identifiers the Universal Address or r_addr (for IPv4) is a US-ASCII string and is of the form: h1.h2.h3.h4.p1.p2 The prefix, "h1.h2.h3.h4", is the standard textual form for @@ -14648,22 +14676,22 @@ 19.1. Normative References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", March 1997. [2] Haynes, T. and D. Noveck, "NFSv4 Version 0 XDR Description", draft-ietf-nfsv4-rfc3530bis-dot-x-02 (work in progress), Feb 2011. - [3] Srinivasan, R., "RPC: Remote Procedure Call Protocol - Specification Version 2", RFC 1831, August 1995. + [3] Thurlow, R., "RPC: Remote Procedure Call Protocol Specification + Version 2", RFC 5531, May 2009. [4] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol Specification", RFC 2203, September 1997. [5] Eisler, M., "LIPKEY - A Low Infrastructure Public Key Mechanism Using SPKM", RFC 2847, June 2000. [6] Linn, J., "Generic Security Service Application Program Interface Version 2, Update 1", RFC 2743, January 2000. @@ -14812,38 +14840,42 @@ contributed substantially to improving the quality of the final 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. + Bruce Fields was a good sounding board for both the Third Edge + Condition and Courtsey Locks in general. + Appendix B. RFC Editor Notes [RFC Editor: please remove this section prior to publishing this document as an RFC] [RFC Editor: prior to publishing this document as an RFC, please replace all occurrences of RFCTBD10 with RFCxxxx where xxxx is the RFC number of this document] Authors' Addresses - Thomas Haynes + Thomas Haynes (editor) NetApp 9110 E 66th St Tulsa, OK 74133 USA Phone: +1 918 307 1415 Email: thomas@netapp.com + URI: http://www.tulsalabs.com - David Noveck - EMC + David Noveck (editor) + EMC Corporation 32 Coslin Drive Southborough, MA 01772 US Phone: +1 508 305 8404 Email: novecd@emc.com